Re: [PATCH v5 1/1] Documentation/process: Be more explicit about who to mail on patch submission

From: Bryan O'Donoghue
Date: Tue Oct 04 2022 - 12:27:16 EST

On 04/10/2022 16:17, Akira Yokosawa wrote:
Hi Bryan,

I'll be silent on the word choice of "supporter" for the time being. :-)

On Tue, 4 Oct 2022 13:48:58 +0100, Bryan O'Donoghue wrote:
Recently when submitting a yaml change I found that I had omitted the
maintainer whose tree the change needed to go through.

The reason for that is the path in MAINTAINERS is marked as Supported not
Maintained. Reading MAINTAINERS we see quote:

Supported: Someone is actually paid to look after this.
Maintained: Someone actually looks after it.

The current submitting-patches.rst only says to mail maintainers though not
supporters. Discussing further on the list the suggestion was made to state
that the following are the right addresses to mail:

- Maintainers
- Supporters
- Reviewers
- Dedicated lists
- LKML as a fallback when there is no dedicated list

Add in a two sentences to capture that statement.

Signed-off-by: Bryan O'Donoghue <bryan.odonoghue@xxxxxxxxxx>
Documentation/process/submitting-patches.rst | 7 +++++--
1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
index be49d8f2601b4..90fda3367a405 100644
--- a/Documentation/process/submitting-patches.rst
+++ b/Documentation/process/submitting-patches.rst
@@ -227,8 +227,11 @@ You should always copy the appropriate subsystem maintainer(s) on any patch
to code that they maintain; look through the MAINTAINERS file and the
source code revision history to see who those maintainers are. The
script scripts/ can be very useful at this step (pass paths to
-your patches as arguments to scripts/ If you cannot find a
-maintainer for the subsystem you are working on, Andrew Morton
+your patches as arguments to scripts/ In the output of the recommendation is to mail every maintainer, supporter,
+reviewer and dedicated mailing list. If get_maintainer doesn't indicate a
+dedicated mailing list linux-kernel@xxxxxxxxxxxxxxx should be included. If you
+cannot find a maintainer for the subsystem you are working on, Andrew Morton
(akpm@xxxxxxxxxxxxxxxxxxxx) serves as a maintainer of last resort.
You should also normally choose at least one mailing list to receive a copy

Quoting subsequent paragraph:

You should also normally choose at least one mailing list to receive a copy
of your patch set. linux-kernel@xxxxxxxxxxxxxxx should be used by default
for all patches, but the volume on that list has caused a number of
developers to tune it out. Look in the MAINTAINERS file for a
subsystem-specific list; your patch will probably get more attention there.
Please do not spam unrelated lists, though.

The paragraph you updated mentions the maintainers (as persons) to
send patches.

The subsequent paragraph talks about mailing lists.

After this patch is applied, they look mostly redundant except for
an important difference. In your patch, Cc: LKML is recommended only
when a subsystem-specific list can not be found. In the subsequent
paragraph, LKML is recommended to be Cc'd by default, in addition
to subsystem-specific lists. Does my interpretation wrong?

Yes I take your point.

It is probably wiser to drop "dedicated" from the sentence.

Doesn't the subsequent paragraph (quoted above) work for you?

Not especially. I think it is a super-semantic distinction but, the word "normally" implies there is also an abnormal case.

"Always" would be a better world than "normally"

If it does, you don't need to mention mail lists in your change.
Otherwise, you also need to tweak/remove the subsequent paragraph.


The sentence I'm posting here pertains to the output of "get_maintainer". I think there is value in having a concise statement to say "take the output of get_maintainer and do X"

I also think having a paragraph that says "you must always send to at least one mailing list" is both direct and true.

You are not _required_ to run get_maintainer to submit a patch, it is simply _suggested_ so in my view the output of get_maintainer doesn't negate the statement that you must mail at least one public mailing list.