[PATCH v2 0/3] Documentation: fix a few typo and wording issues

[PATCH v2 0/3] Documentation: fix a few typo and wording issues

[岳秉坤]

Hi,

This series fixes a few small documentation issues (spelling/wording)
across Documentation/ files. Each patch targets a single subsystem's
docs so the respective maintainers can pick them up independently.
These changes are limited to spelling and wording corrections and do
not change behavior.

I am a newcomer to the Linux community, and I am eager to contribute
and learn through small, helpful fixes like this one.

Changes in v2:
- Split the original single combined patch into per-subsystem patches,
  per Randy Dunlap's feedback on v1.
- Moved the "newcomer" note out of the individual commit messages; it
  now lives only in this cover letter.
- Collected Acked-by from Randy Dunlap <rdunlap@infradead.org>. The
  content per-file is unchanged from v1, so the Ack is carried forward
  on each patch.

岳秉坤 (3):
  Documentation: fix "should be use" grammar in ABI README
  Documentation: fix "readng" typo in EDAC memory-repair ABI doc
  Documentation: fix "thare are" typo in V4L subdev routing doc

 Documentation/ABI/README                                        | 2 +-
 Documentation/ABI/testing/sysfs-edac-memory-repair              | 2 +-
 .../userspace-api/media/v4l/vidioc-subdev-g-routing.rst         | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

-- 
2.25.1

[PATCH v2 1/3] Documentation: fix "should be use" grammar in ABI README

[岳秉坤]

Fix "should be use" -> "should use" in Documentation/ABI/README.

Signed-off-by: 岳秉坤 <yuebingkun@kylinos.cn>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
---
 Documentation/ABI/README | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/ABI/README b/Documentation/ABI/README
index 315fffe1f831f..27c962e6a872c 100644
--- a/Documentation/ABI/README
+++ b/Documentation/ABI/README
@@ -62,7 +62,7 @@ Users:		All users of this interface who wish to be notified when
 
 
 Note:
-   The fields should be use a simple notation, compatible with ReST markup.
+   The fields should use a simple notation, compatible with ReST markup.
    Also, the file **should not** have a top-level index, like::
 
 	===
-- 
2.25.1

[PATCH v2 2/3] Documentation: fix "readng" typo in EDAC memory-repair ABI doc

[岳秉坤]

Fix "readng" -> "reading" in
Documentation/ABI/testing/sysfs-edac-memory-repair.

Signed-off-by: 岳秉坤 <yuebingkun@kylinos.cn>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
---
 Documentation/ABI/testing/sysfs-edac-memory-repair | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/ABI/testing/sysfs-edac-memory-repair b/Documentation/ABI/testing/sysfs-edac-memory-repair
index 0434a3b23ff3e..ab199132ffd8a 100644
--- a/Documentation/ABI/testing/sysfs-edac-memory-repair
+++ b/Documentation/ABI/testing/sysfs-edac-memory-repair
@@ -160,7 +160,7 @@ Description:
 		in trace events, such as CXL DRAM and CXL general media
 		error records of CXL memory devices.
 
-		When readng back these attributes, it returns the current
+		When reading back these attributes, it returns the current
 		value of memory requested to be repaired.
 
 		bank_group - The bank group of the memory to repair.
-- 
2.25.1

[PATCH v2 3/3] Documentation: fix "thare are" typo in V4L subdev routing doc

[岳秉坤]

Fix "thare are" -> "there are" in
Documentation/userspace-api/media/v4l/vidioc-subdev-g-routing.rst.

Signed-off-by: 岳秉坤 <yuebingkun@kylinos.cn>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
---
 .../userspace-api/media/v4l/vidioc-subdev-g-routing.rst         | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-routing.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-routing.rst
index 6f66ca38589e8..164cf0ad35931 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-subdev-g-routing.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-g-routing.rst
@@ -67,7 +67,7 @@ subdevice routing table. This may be smaller or larger than the value of
 drivers may adjust the requested routing table.
 
 The kernel can return a ``num_routes`` value larger than ``len_routes`` from
-both ioctls. This indicates thare are more routes in the routing table than fits
+both ioctls. This indicates there are more routes in the routing table than fits
 the ``routes`` array. In this case, the ``routes`` array is filled by the kernel
 with the first ``len_routes`` entries of the subdevice routing table. This is
 not considered to be an error, and the ioctl call succeeds. If the applications
-- 
2.25.1

Re: [PATCH v2 1/3] Documentation: fix "should be use" grammar in ABI README

[Weijie Yuan]

Hi 秉坤,

On Tue, Jul 28, 2026 at 12:12:11PM +0800, 岳秉坤 wrote:
> Fix "should be use" -> "should use" in Documentation/ABI/README.

The diff below already documents that the changes is in
"Documentation/ABI/README". I'm not sure if it is proper to write like
this. But I also do not know what's the best practice to write commit
messages for typos. Hope some friends could provide a better answer ;-)
Of course, if the maintainer thinks it's okay, I'll be definitely fine
with it.

> Signed-off-by: 岳秉坤 <yuebingkun@kylinos.cn>
> Acked-by: Randy Dunlap <rdunlap@infradead.org>

Usually, your "Signed-off-by" should be the last trailer.

> ---
>  Documentation/ABI/README | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/Documentation/ABI/README b/Documentation/ABI/README
> index 315fffe1f831f..27c962e6a872c 100644
> --- a/Documentation/ABI/README
> +++ b/Documentation/ABI/README

Thanks.

Re: [PATCH v2 1/3] Documentation: fix "should be use" grammar in ABI README

[Randy Dunlap]

On 7/27/26 9:24 PM, Weijie Yuan wrote:
> Hi 秉坤,
> 
> On Tue, Jul 28, 2026 at 12:12:11PM +0800, 岳秉坤 wrote:
>> Fix "should be use" -> "should use" in Documentation/ABI/README.
> 
> The diff below already documents that the changes is in
> "Documentation/ABI/README". I'm not sure if it is proper to write like
> this. But I also do not know what's the best practice to write commit
> messages for typos. Hope some friends could provide a better answer ;-)
> Of course, if the maintainer thinks it's okay, I'll be definitely fine
> with it.
> 
>> Signed-off-by: 岳秉坤 <yuebingkun@kylinos.cn>
>> Acked-by: Randy Dunlap <rdunlap@infradead.org>
> 
> Usually, your "Signed-off-by" should be the last trailer.

Hm, I disagree. The -by: lines are somewhat in chronological order, so this
looks fine to me.

Documentation/process/submitting-patches.rst says:
"""
Standard sign-off
procedure applies, i.e. the ordering of Signed-off-by: tags should reflect the
chronological history of the patch insofar as possible, regardless of whether
the author is attributed via From: or Co-developed-by:.  Notably, the last
Signed-off-by: must always be that of the developer submitting the patch.
"""

Yes, this doesn't address Acked-by: or Reviewed-by: lines, but in my experience,
chronological order applies to all of them.


>> ---
>>  Documentation/ABI/README | 2 +-
>>  1 file changed, 1 insertion(+), 1 deletion(-)
>>
>> diff --git a/Documentation/ABI/README b/Documentation/ABI/README
>> index 315fffe1f831f..27c962e6a872c 100644
>> --- a/Documentation/ABI/README
>> +++ b/Documentation/ABI/README
> 
> Thanks.

-- 
~Randy

Re: [PATCH v2 1/3] Documentation: fix "should be use" grammar in ABI README

[Weijie Yuan]

On Mon, Jul 27, 2026 at 09:31:35PM -0700, Randy Dunlap wrote:
> >> Signed-off-by: 岳秉坤 <yuebingkun@kylinos.cn>
> >> Acked-by: Randy Dunlap <rdunlap@infradead.org>
> > 
> > Usually, your "Signed-off-by" should be the last trailer.
> 
> Hm, I disagree. The -by: lines are somewhat in chronological order, so this
> looks fine to me.
> 
> Documentation/process/submitting-patches.rst says:
> """
> Standard sign-off
> procedure applies, i.e. the ordering of Signed-off-by: tags should reflect the
> chronological history of the patch insofar as possible, regardless of whether
> the author is attributed via From: or Co-developed-by:.  Notably, the last
> Signed-off-by: must always be that of the developer submitting the patch.
> """
> 
> Yes, this doesn't address Acked-by: or Reviewed-by: lines, but in my experience,
> chronological order applies to all of them.

Ah, I remember this part. But I tend to believe that this description is
only relevant to the issue of the order of Co-authored-by and
Signed-off-by, if I were the newcomer reading this for the first time.
(In fact, I actually am a newcomer compared with you ;-))

That is to say, when dealing with multiple authors, we suggest using
trailers to represent the sequence of authors in chronological order.

Then, this will facilitate subsequent readers to understand the
development history of the patch through the order of the trailers.(?)

And, aren't these subsequent examples merely confining the discussion to
these two trailers?

---
<changelog>

Co-developed-by: First Co-Author <first@coauthor.example.org>
Signed-off-by: First Co-Author <first@coauthor.example.org>
Co-developed-by: Second Co-Author <second@coauthor.example.org>
Signed-off-by: Second Co-Author <second@coauthor.example.org>
Signed-off-by: From Author <from@author.example.org>
---

Besides the submitting-patches file, It seems to me that the probability
of "Signed-off-by" appearing on the last line is much higher than in
other cases. Is this a usual practice? It seems that everyone tacitly
agreed to write "Acked-by" and "Reviewed-by" at the top, even though
they occurred after "Sob".

But of course, you have much more experience in this area, so my limited
observations may not be very representative.

Thanks!

ps. The Git project explicitly stipulates "Place this `Signed-off-by:`
trailer at the end". So at first, I wasn't quite sure about it.

Re: [PATCH v2 1/3] Documentation: fix "should be use" grammar in ABI README

[Randy Dunlap]

On 7/27/26 10:48 PM, Weijie Yuan wrote:
> On Mon, Jul 27, 2026 at 09:31:35PM -0700, Randy Dunlap wrote:
>>>> Signed-off-by: 岳秉坤 <yuebingkun@kylinos.cn>
>>>> Acked-by: Randy Dunlap <rdunlap@infradead.org>
>>>
>>> Usually, your "Signed-off-by" should be the last trailer.
>>
>> Hm, I disagree. The -by: lines are somewhat in chronological order, so this
>> looks fine to me.
>>
>> Documentation/process/submitting-patches.rst says:
>> """
>> Standard sign-off
>> procedure applies, i.e. the ordering of Signed-off-by: tags should reflect the
>> chronological history of the patch insofar as possible, regardless of whether
>> the author is attributed via From: or Co-developed-by:.  Notably, the last
>> Signed-off-by: must always be that of the developer submitting the patch.
>> """
>>
>> Yes, this doesn't address Acked-by: or Reviewed-by: lines, but in my experience,
>> chronological order applies to all of them.
> 
> Ah, I remember this part. But I tend to believe that this description is
> only relevant to the issue of the order of Co-authored-by and
> Signed-off-by, if I were the newcomer reading this for the first time.
> (In fact, I actually am a newcomer compared with you ;-))

Yes, that's understandable.

> That is to say, when dealing with multiple authors, we suggest using
> trailers to represent the sequence of authors in chronological order.
> 
> Then, this will facilitate subsequent readers to understand the
> development history of the patch through the order of the trailers.(?)
> 
> And, aren't these subsequent examples merely confining the discussion to
> these two trailers?

They seem to be but that's just a documentation deficiency IMO.

> ---
> <changelog>
> 
> Co-developed-by: First Co-Author <first@coauthor.example.org>
> Signed-off-by: First Co-Author <first@coauthor.example.org>
> Co-developed-by: Second Co-Author <second@coauthor.example.org>
> Signed-off-by: Second Co-Author <second@coauthor.example.org>
> Signed-off-by: From Author <from@author.example.org>
> ---
> 
> Besides the submitting-patches file, It seems to me that the probability
> of "Signed-off-by" appearing on the last line is much higher than in
> other cases. Is this a usual practice? It seems that everyone tacitly
> agreed to write "Acked-by" and "Reviewed-by" at the top, even though
> they occurred after "Sob".
> 

I chose 2 files and looked at their "git log" history: MAINTAINERS and
kernel/panic.c. In those files I see corroboration of my "claim," so I'm
satisfied with it.

> But of course, you have much more experience in this area, so my limited
> observations may not be very representative.
> 
> Thanks!
> 
> ps. The Git project explicitly stipulates "Place this `Signed-off-by:`
> trailer at the end". So at first, I wasn't quite sure about it.

-- 
~Randy

Re: [PATCH v2 1/3] Documentation: fix "should be use" grammar in ABI README

[Weijie Yuan]

On Tue, Jul 28, 2026 at 09:55:42AM -0700, Randy Dunlap wrote:
> > That is to say, when dealing with multiple authors, we suggest using
> > trailers to represent the sequence of authors in chronological order.
> > 
> > Then, this will facilitate subsequent readers to understand the
> > development history of the patch through the order of the trailers.(?)
> > 
> > And, aren't these subsequent examples merely confining the discussion to
> > these two trailers?
> 
> They seem to be but that's just a documentation deficiency IMO.

OK, let me take some time to look through the history of this file and
see if I can uncover any clues.

If this is indeed a flaw, it might be worth clarifying. That said, I am
not sure how many people actually find it ambiguous. In any case, it may
be better for someone with more experience to improve it, as I am
clearly not qualified to do so.

> > Besides the submitting-patches file, It seems to me that the probability
> > of "Signed-off-by" appearing on the last line is much higher than in
> > other cases. Is this a usual practice? It seems that everyone tacitly
> > agreed to write "Acked-by" and "Reviewed-by" at the top, even though
> > they occurred after "Sob".
> > 
> 
> I chose 2 files and looked at their "git log" history: MAINTAINERS and
> kernel/panic.c. In those files I see corroboration of my "claim," so I'm
> satisfied with it.

Makes sense. Perhaps different subsystems simply have different
preferences, then. My observation may not have been representative.

Thanks.

RE: [PATCH v2 1/3] Documentation: fix "should be use" grammar in ABI README

[Luck, Tony]

> Makes sense. Perhaps different subsystems simply have different
> preferences, then. My observation may not have been representative.

Yes. TIP tree for x86 core work provides an explicit order for tags. See
"Documentation/process/maintainer-tip.rst" in the " Ordering of commit tags"
section.

-Tony

Re: [PATCH v2 1/3] Documentation: fix "should be use" grammar in ABI README

[Weijie Yuan]

On Tue, Jul 28, 2026 at 05:25:47PM +0000, Luck, Tony wrote:
> > Makes sense. Perhaps different subsystems simply have different
> > preferences, then. My observation may not have been representative.
> 
> Yes. TIP tree for x86 core work provides an explicit order for tags. See
> "Documentation/process/maintainer-tip.rst" in the " Ordering of commit tags"
> section.
> 
> -Tony

Hi Tony, thanks for mentioning this!

To be honest, I usually read the documentation only on docs.kernel.org,
and I'm only now realizing how much I´ve been missing... as many files
are not listed in index.rst.

Thanks! Learned a lot.