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

[Bryan O'Donoghue]

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/get_maintainer.pl can be very useful at this step (pass paths to
> > -your patches as arguments to scripts/get_maintainer.pl).  If you cannot find a
> > -maintainer for the subsystem you are working on, Andrew Morton
> > +your patches as arguments to scripts/get_maintainer.pl).  In the output of
> > +get_maintainer.pl 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.
>
> Thoughts?

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.

---
bod