[PATCH v3 0/1] Expand get_maintainer to be explicit about supporters

[PATCH v3 0/1] Expand get_maintainer to be explicit about supporters

[Bryan O'Donoghue]

V3:

- Drops change to get_maintainer.pl - Theodore
- Rewords around `get_maintainer --nogit-fallback` and gives an example

I think the document text now is clearer and should be more helpful to
others in getting their minimum submission list right every time.

V2:

https://lore.kernel.org/lkml/20220928003006.230103-1-bryan.odonoghue@linaro.org/T/#u

- Documentation/process
  Added in text to also make clear subsystem mailing list should be
  included - Krzysztof

- Changed get_maintainer.pl to print maintainer[supporter] or
  maintainer[volunteer] depending on MAINTAINERS file. - Thorsten/Bryan

- Choose supporter and volunteer instead of supported and volunteer
  Supporter and volunteer describe the role of the person whereas supported
  and volunteer would describe an activity and a role which isn't
  consistent. - Thorsten/Bryan

- I didn't change Documentation/process/5.Posting.rst
  This file doesn't mention get_maintainer.pl and I was mostly aiming to
  fixup the process around get_maintainer.pl. - Thorsten

- Myself and Thorsten discussed changing get_maintainer.pl, how it seems
  like a desirable thing to do but also that "it might break scripts for
  people" and it might.

  I don't know if get_maintainer.pl is or should be considered to be a
  stable interface and an explicit software contract but, making it clear a
  supporter is also a maintainer seems like the right thing to do from a
  transmission of information perspective.

  There is still the option of just updating Documentation/process in
  isolation.

V1:
- Sent a standalone change to Documentation/process stating
  get_maintainer.pl email addresses marked "supporter" should be included
  in a patch run.

Bryan O'Donoghue (1):
  Documentation/process: Add text to indicate supporters should be
    mailed

 Documentation/process/submitting-patches.rst | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

-- 
2.37.3

[PATCH v3] Documentation/process: Add text to indicate supporters should be mailed

[Bryan O'Donoghue]

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. When we run scripts/get_maintainer.pl anybody who is denoted a
paid maintainer will appear as a supporter.

Add text to state that every mail address returned by get_maintainer.pl
--nogit-fallback should be included when submitting a patch, giving an
example of the same.

Signed-off-by: Bryan O'Donoghue <bryan.odonoghue@linaro.org>
---
 Documentation/process/submitting-patches.rst | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
index be49d8f2601b4..18a1f52e0563a 100644
--- a/Documentation/process/submitting-patches.rst
+++ b/Documentation/process/submitting-patches.rst
@@ -227,9 +227,15 @@ 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
-(akpm@linux-foundation.org) serves as a maintainer of last resort.
+your patches as arguments to scripts/get_maintainer.pl).  You should mail every
+email address returned by `scripts/get_maintainer.pl --nogit-fallback` when
+submitting a patch.
+For example::
+
+    $ scripts/get_maintainer.pl --nogit-fallback -f submitting-patches.rst
+    Jonathan Corbet <corbet@lwn.net> (maintainer:DOCUMENTATION)
+    linux-doc@vger.kernel.org (open list:DOCUMENTATION)
+    linux-kernel@vger.kernel.org (open list)
 
 You should also normally choose at least one mailing list to receive a copy
 of your patch set.  linux-kernel@vger.kernel.org should be used by default
-- 
2.37.3

Re: [PATCH v3] Documentation/process: Add text to indicate supporters should be mailed

[Akira Yokosawa]

Hi,

On Fri, 30 Sep 2022 07:46:29 +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. When we run scripts/get_maintainer.pl anybody who is denoted a
> paid maintainer will appear as a supporter.

So the root cause of your confusion was you couldn't figure out
the fact that "supporter" in the output of get_maintainver.pl means
"maintainer of a supported subsystem", wasn't it?

I guess all you need would be just a short notice along the lines of:

    "supporter" in the output from get_maintainer.pl means "maintainer
    of a supported subsystem".

No?

> 
> Add text to state that every mail address returned by get_maintainer.pl
> --nogit-fallback should be included when submitting a patch, giving an
> example of the same.> 
> Signed-off-by: Bryan O'Donoghue <bryan.odonoghue@linaro.org>
> ---
>  Documentation/process/submitting-patches.rst | 12 +++++++++---
>  1 file changed, 9 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
> index be49d8f2601b4..18a1f52e0563a 100644
> --- a/Documentation/process/submitting-patches.rst
> +++ b/Documentation/process/submitting-patches.rst
> @@ -227,9 +227,15 @@ 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
> -(akpm@linux-foundation.org) serves as a maintainer of last resort.
> +your patches as arguments to scripts/get_maintainer.pl).  You should mail every
> +email address returned by `scripts/get_maintainer.pl --nogit-fallback` when
> +submitting a patch.
> +For example::
> +
> +    $ scripts/get_maintainer.pl --nogit-fallback -f submitting-patches.rst
> +    Jonathan Corbet <corbet@lwn.net> (maintainer:DOCUMENTATION)
> +    linux-doc@vger.kernel.org (open list:DOCUMENTATION)
> +    linux-kernel@vger.kernel.org (open list)

This example has a number of issues...

 1) The command line doesn't work when run under the top of kernel tree.
 2) The -f flag contradicts the instruction above:
    (pass paths to your *patches* as arguments to scripts/get_maintainer.pl).
 3) There can be cases where --git-fallback (default) is useful.
 4) The output can change any time.
 5) There is no point in using Jon's actual name and email address.

Why not just add a short notice I mentioned above as a first step?

Please take your time before sending out v4 to make sure your change
will improve things.

Regards,
Akira

>  
>  You should also normally choose at least one mailing list to receive a copy
>  of your patch set.  linux-kernel@vger.kernel.org should be used by default

Re: [PATCH v3] Documentation/process: Add text to indicate supporters should be mailed

[Bryan O'Donoghue]

On 30/09/2022 15:47, Akira Yokosawa wrote:
> Hi,
> 
> On Fri, 30 Sep 2022 07:46:29 +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. When we run scripts/get_maintainer.pl anybody who is denoted a
>> paid maintainer will appear as a supporter.
> 
> So the root cause of your confusion was you couldn't figure out
> the fact that "supporter" in the output of get_maintainver.pl means
> "maintainer of a supported subsystem", wasn't it?
> 
> I guess all you need would be just a short notice along the lines of:
> 
>      "supporter" in the output from get_maintainer.pl means "maintainer
>      of a supported subsystem".
> 
> No?

We discussed that a bit earlier.

https://lore.kernel.org/lkml/20220928003006.230103-1-bryan.odonoghue@linaro.org/T/#u
https://lkml.org/lkml/2022/9/28/1394
https://lkml.org/lkml/2022/9/28/1511
https://lkml.org/lkml/2022/9/29/188

I think its fair to say the consensus so far is to leave the 
get_maintainer.pl output as is.

>>
>> Add text to state that every mail address returned by get_maintainer.pl
>> --nogit-fallback should be included when submitting a patch, giving an
>> example of the same.>
>> Signed-off-by: Bryan O'Donoghue <bryan.odonoghue@linaro.org>
>> ---
>>   Documentation/process/submitting-patches.rst | 12 +++++++++---
>>   1 file changed, 9 insertions(+), 3 deletions(-)
>>
>> diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
>> index be49d8f2601b4..18a1f52e0563a 100644
>> --- a/Documentation/process/submitting-patches.rst
>> +++ b/Documentation/process/submitting-patches.rst
>> @@ -227,9 +227,15 @@ 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
>> -(akpm@linux-foundation.org) serves as a maintainer of last resort.
>> +your patches as arguments to scripts/get_maintainer.pl).  You should mail every
>> +email address returned by `scripts/get_maintainer.pl --nogit-fallback` when
>> +submitting a patch.
>> +For example::
>> +
>> +    $ scripts/get_maintainer.pl --nogit-fallback -f submitting-patches.rst
>> +    Jonathan Corbet <corbet@lwn.net> (maintainer:DOCUMENTATION)
>> +    linux-doc@vger.kernel.org (open list:DOCUMENTATION)
>> +    linux-kernel@vger.kernel.org (open list)
> 
> This example has a number of issues...
> 
>   1) The command line doesn't work when run under the top of kernel tree.

Well I didn't want to exceed 80 characters but I have no problem make it 
top level explicit

>   2) The -f flag contradicts the instruction above:
>      (pass paths to your *patches* as arguments to scripts/get_maintainer.pl).

I'm not sure I follow how it contradicts but, I will read it again.

>   3) There can be cases where --git-fallback (default) is useful.

Can you elaborate what your thinking is on that. I'm happy to try to 
include it in the instructions we give.

>   4) The output can change any time.

What does this mean ? The output won't change for a given patch you are 
trying to send.

Do you mean the output of get_maintainer.pl can change ?

It could but, how does that negate the value of documenting what it does 
right now ?

>   5) There is no point in using Jon's actual name and email address.

Sure, I see your point. I'll use a fake email.


> Why not just add a short notice I mentioned above as a first step?

Please see above.

---
bod

Re: [PATCH v3] Documentation/process: Add text to indicate supporters should be mailed

[Bryan O'Donoghue]

On 30/09/2022 17:18, Bryan O'Donoghue wrote:
> I guess all you need would be just a short notice along the lines of:
> 
>       "supporter" in the output from get_maintainer.pl means "maintainer
>       of a supported subsystem".
> 
> No?

Ah I see you are suggesting a document not a get_maintainer.pl edit, my 
mistake.

Yes, I'm fine to change the text to something like this if you feel it 
reads better that way.

I'd still appreciate some more eloboration/rationale on what you don't 
like about giving an example.

Is it the example in general you dislike ? Personally I find an example 
a useful thing but, that's just a personal preference.

---
bod

Re: [PATCH v3] Documentation/process: Add text to indicate supporters should be mailed

[Theodore Ts'o]

On Fri, Sep 30, 2022 at 05:18:52PM +0100, Bryan O'Donoghue wrote:
> > So the root cause of your confusion was you couldn't figure out
> > the fact that "supporter" in the output of get_maintainver.pl means
> > "maintainer of a supported subsystem", wasn't it?
> > 
> > I guess all you need would be just a short notice along the lines of:
> > 
> >      "supporter" in the output from get_maintainer.pl means "maintainer
> >      of a supported subsystem".
> > 
> > No?
> 
> We discussed that a bit earlier.
> 
> https://lore.kernel.org/lkml/20220928003006.230103-1-bryan.odonoghue@linaro.org/T/#u
> https://lkml.org/lkml/2022/9/28/1394
> https://lkml.org/lkml/2022/9/28/1511
> https://lkml.org/lkml/2022/9/29/188
> 
> I think its fair to say the consensus so far is to leave the
> get_maintainer.pl output as is.


FWIW, I actually think the output of get_maintainer.pl is pretty
broken in this regard.  (Then again, I've never thought all that
highly of get_maintainer.pl, *especially* because of the bogus git
fallback, but that's another story.)

Consider:

% ./scripts/get_maintainer.pl --file  drivers/acpi/power.c
"Rafael J. Wysocki" <rafael@kernel.org> (supporter:ACPI)
Len Brown <lenb@kernel.org> (reviewer:ACPI)
linux-acpi@vger.kernel.org (open list:ACPI)
linux-kernel@vger.kernel.org (open list)

I'm sorry, but that's just *wrong*.  Rafael is the *maintainer* of the
ACPI subsystem, and the term "supporter" is rarely if ever used
anywhere in our docs.  As I said earlier, trying to treat S: field to
say anything about the entitles listed under the M: field of the
Maintainers file is a category error.

Consider: ACPI subsystem is is "supported".  From a user's
perspective, what are they supposed to take from that?  That the ACPI
subsystem is somehow better supported than say, the MM subsystem
(which is only "maintained"), or all of Linux networking, which is
also "maintained".  And so Rafel is a "supporter", but David Miller
and Andrew Morton are "maintainers", respectively. ?!?

I think the original rationale behind the S: field is to help people
understand, in particular for device drivers, how solid a particular
device driver might be.  Was it officially supported by the hardware
manufacturer?  Was it supported by a some random student who hacked
something together?  Was the still being actively maintained?  But
even then, just because a driver is "officially" supported by the
hardware manufacturer doesn't necessarily mean that it is any more
reliable, or high quality, than something which is being supported by
someone who supposedly isn't getting paid to support it.  (And there
are plenty of subsystems listed as "maintained" where the people
listed under M: are most certainly getting paid to work on it.)

       	     	    	 	   	   - Ted

Re: [PATCH v3] Documentation/process: Add text to indicate supporters should be mailed

[Bryan O'Donoghue]

On 01/10/2022 03:37, Theodore Ts'o wrote:
> FWIW, I actually think the output of get_maintainer.pl is pretty
> broken in this regard.  (Then again, I've never thought all that
> highly of get_maintainer.pl,*especially*  because of the bogus git
> fallback, but that's another story.)
> 
> Consider:
> 
> % ./scripts/get_maintainer.pl --file  drivers/acpi/power.c
> "Rafael J. Wysocki"<rafael@kernel.org>  (supporter:ACPI)
> Len Brown<lenb@kernel.org>  (reviewer:ACPI)
> linux-acpi@vger.kernel.org  (open list:ACPI)
> linux-kernel@vger.kernel.org  (open list)
> 
> I'm sorry, but that's just*wrong*.  Rafael is the*maintainer*  of the
> ACPI subsystem, and the term "supporter" is rarely if ever used
> anywhere in our docs.  As I said earlier, trying to treat S: field to
> say anything about the entitles listed under the M: field of the
> Maintainers file is a category error.

I agree, I made exactly this error.

I wasn't sure how people would necessarily feel about having 
get_maintainer produce the string 'maintainer' for both Maintained and 
Supported but, IMO it is more consistent to have it do so, since we 
refer to maintainers all throughout the doucmentation and as you say 
above Rafael is the person you *need* to mail there because he's the 
maintainer.

Lets consider

- maintainer as a string for "S: Supported"
- Documentation update to reflect Krzysztof's point on git-fallback

---
bod

Re: [PATCH v3] Documentation/process: Add text to indicate supporters should be mailed

[Akira Yokosawa]

On Sat, 1 Oct 2022 11:37:03 +0100, Bryan O'Donoghue wrote:
> On 01/10/2022 03:37, Theodore Ts'o wrote:
>> FWIW, I actually think the output of get_maintainer.pl is pretty
>> broken in this regard.  (Then again, I've never thought all that
>> highly of get_maintainer.pl,*especially*  because of the bogus git
>> fallback, but that's another story.)
>>
>> Consider:
>>
>> % ./scripts/get_maintainer.pl --file  drivers/acpi/power.c
>> "Rafael J. Wysocki"<rafael@kernel.org>  (supporter:ACPI)
>> Len Brown<lenb@kernel.org>  (reviewer:ACPI)
>> linux-acpi@vger.kernel.org  (open list:ACPI)
>> linux-kernel@vger.kernel.org  (open list)
>>
>> I'm sorry, but that's just*wrong*.  Rafael is the*maintainer*  of the
>> ACPI subsystem, and the term "supporter" is rarely if ever used
>> anywhere in our docs.  As I said earlier, trying to treat S: field to
>> say anything about the entitles listed under the M: field of the
>> Maintainers file is a category error.
> 
> I agree, I made exactly this error.
> 
> I wasn't sure how people would necessarily feel about having
> get_maintainer produce the string 'maintainer' for both Maintained and
> Supported but, IMO it is more consistent to have it do so, since we refer
> to maintainers all throughout the doucmentation and as you say above Rafael
> is the person you *need* to mail there because he's the maintainer.

You'd better CC Joe Perches, who is the maintainer of get_maintainer.pl.
You might want to start a new thread with a different subject.
The main point becomes the behavior of get_maintainer.pl.

> 
> Lets consider
> 
> - maintainer as a string for "S: Supported"
> - Documentation update to reflect Krzysztof's point on git-fallback

Sounds reasonable to me.
Good luck!

Thanks,
Akira

> 
> ---
> bod

Re: [PATCH v3] Documentation/process: Add text to indicate supporters should be mailed

[Krzysztof Kozlowski]

On 01/10/2022 12:37, Bryan O'Donoghue wrote:
> 
> I wasn't sure how people would necessarily feel about having 
> get_maintainer produce the string 'maintainer' for both Maintained and 
> Supported but, IMO it is more consistent to have it do so, since we 
> refer to maintainers all throughout the doucmentation and as you say 
> above Rafael is the person you *need* to mail there because he's the 
> maintainer.
> 
> Lets consider
> 
> - maintainer as a string for "S: Supported"
> - Documentation update to reflect Krzysztof's point on git-fallback

Just to clarify my point - one can use git-fallback. The expectation is
however that submitter CCs all specifically assigned addresses from
maintainers, this is:
 - all maintainers
 - all maintainers-supporters
 - all reviewers
 - all dedicated mailing lists
 - LKML if there is no dedicated mailing list.

The easiest to achieve it is to run with --no-git-fallback and CC entire
output. However it does not mean submitter must run with
--no-git-fallback. It is only for this generic rule - CC entire output
of get_maintainers.pl.

If you add such rule "CC entire output of get_maintainers.pl" and do not
mention no-git-fallback, some folks will think they need to CC all these
people who made one commit to your file...

Best regards,
Krzysztof

Re: [PATCH v3] Documentation/process: Add text to indicate supporters should be mailed

[Joe Perches]

On Sun, 2022-10-02 at 09:58 +0200, Krzysztof Kozlowski wrote:
> The easiest to achieve it is to run with --no-git-fallback and CC entire
> output. However it does not mean submitter must run with
> --no-git-fallback. It is only for this generic rule - CC entire output
> of get_maintainers.pl.
> 
> If you add such rule "CC entire output of get_maintainers.pl" and do not
> mention no-git-fallback, some folks will think they need to CC all these
> people who made one commit to your file...

false.

git-fallback is _not_ used when there is a listed maintainer for a
specific file.

If there is a use of git-fallback, it's because there is _no_
specified maintainer for a specific file.

   --git-fallback => use git when no exact MAINTAINERS pattern (default: 1)

i.e.: It's not "your file" if you don't maintain it.

Re: [PATCH v3] Documentation/process: Add text to indicate supporters should be mailed

[Akira Yokosawa]

Hello Joe,

Thank you for chiming in.

On 2022/10/03 0:49, Joe Perches wrote:
> On Sun, 2022-10-02 at 09:58 +0200, Krzysztof Kozlowski wrote:
>> The easiest to achieve it is to run with --no-git-fallback and CC entire
>> output. However it does not mean submitter must run with
>> --no-git-fallback. It is only for this generic rule - CC entire output
>> of get_maintainers.pl.
>>
>> If you add such rule "CC entire output of get_maintainers.pl" and do not
>> mention no-git-fallback, some folks will think they need to CC all these
>> people who made one commit to your file...
> 
> false.
> 
> git-fallback is _not_ used when there is a listed maintainer for a
> specific file.
> 
> If there is a use of git-fallback, it's because there is _no_
> specified maintainer for a specific file.
> 
>    --git-fallback => use git when no exact MAINTAINERS pattern (default: 1)
> 
> i.e.: It's not "your file" if you don't maintain it.

Joe, I sometimes see unexpected output WRT --git-fallback.

Example:

    $ ./get_maintainer.pl -f Documentation/doc-guide/sphinx.rst
    Jonathan Corbet <corbet@lwn.net> (maintainer:DOCUMENTATION,commit_signer:1/1=100%)
  <-- ???
    Lukas Bulwahn <lukas.bulwahn@gmail.com> (commit_signer:1/1=100%,authored:1/1=100%,added_lines:2/2=100%,removed_lines:2/2=100%)
    <-- ???
    linux-doc@vger.kernel.org (open list:DOCUMENTATION)

    linux-kernel@vger.kernel.org (open list)

As you see, --git-fallback is used in this case. Why?
It looks strange to me as Jon is listed as a "maintainer".

Having "F:	Documentation/" in MAINTAINERS does not suffice?

Can you elaborate?

Regards,
Akira

Re: [PATCH v3] Documentation/process: Add text to indicate supporters should be mailed

[Joe Perches]

On Mon, 2022-10-03 at 08:04 +0900, Akira Yokosawa wrote:
> Hello Joe,
> 
> Thank you for chiming in.
> 
> On 2022/10/03 0:49, Joe Perches wrote:
> > On Sun, 2022-10-02 at 09:58 +0200, Krzysztof Kozlowski wrote:
> > > The easiest to achieve it is to run with --no-git-fallback and CC entire
> > > output. However it does not mean submitter must run with
> > > --no-git-fallback. It is only for this generic rule - CC entire output
> > > of get_maintainers.pl.
> > > 
> > > If you add such rule "CC entire output of get_maintainers.pl" and do not
> > > mention no-git-fallback, some folks will think they need to CC all these
> > > people who made one commit to your file...
> > 
> > false.
> > 
> > git-fallback is _not_ used when there is a listed maintainer for a
> > specific file.
> > 
> > If there is a use of git-fallback, it's because there is _no_
> > specified maintainer for a specific file.
> > 
> >    --git-fallback => use git when no exact MAINTAINERS pattern (default: 1)
> > 
> > i.e.: It's not "your file" if you don't maintain it.
> 
> Joe, I sometimes see unexpected output WRT --git-fallback.
> 
> Example:
> 
>     $ ./get_maintainer.pl -f Documentation/doc-guide/sphinx.rst
>     Jonathan Corbet <corbet@lwn.net> (maintainer:DOCUMENTATION,commit_signer:1/1=100%)
>   <-- ???
>     Lukas Bulwahn <lukas.bulwahn@gmail.com> (commit_signer:1/1=100%,authored:1/1=100%,added_lines:2/2=100%,removed_lines:2/2=100%)
>     <-- ???
>     linux-doc@vger.kernel.org (open list:DOCUMENTATION)
> 
>     linux-kernel@vger.kernel.org (open list)
> 
> As you see, --git-fallback is used in this case. Why?
> It looks strange to me as Jon is listed as a "maintainer".
> 
> Having "F:	Documentation/" in MAINTAINERS does not suffice?

No.  It's not an exact pattern match as the files below the
top level of Documentation are not specifically matched by
"F:	Documentation/".

Just as David Miller is not the direct maintainer for every
driver under drivers/net, Jonathan Corbet is not the direct
maintainer for every file under Documentation.

There are many specific listed maintainer for files under the
Documentation directory.  Jonathan would be cc'd though on all
files in the Documentation directory (save those excluded by
X: entries in his section)

Anyway, git-fallback is used because of the lack of specific
maintainer for many of the files in the Documentation/ tree.

$ git ls-files Documentation | \
  grep -vP '^(?:Documentation/ABI|Documentation/admin-guide/media|Documentation/devicetree|Documentation/driver-api|Documentation/firmware-guide/acpi|Documentation/i2c|Documentation/power|Documentation/spi|Documentation/userspace-api)' | \
  wc -l
2449

Of those ~2.4K files, many are actually maintained by others.

Many are not.  By running a little script, about half are not
directly maintained by anyone.

and lastly:

Using git-blame on that file, it seems to me that Mauro Carvelo Chehab
would be a good recipient too.

$ ./scripts/get_maintainer.pl --git-blame Documentation/doc-guide/sphinx.rst
Jonathan Corbet <corbet@lwn.net> (maintainer:DOCUMENTATION,commit_signer:8/8=100%,authored:1/8=12%,added_lines:5/42=12%,removed_lines:6/23=26%,modified commits:25/25=100%)
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> (commit_signer:4/8=50%,authored:3/8=38%,added_lines:12/42=29%,modified commits:12/25=48%)
Akira Yokosawa <akiyks@gmail.com> (commit_signer:3/8=38%,authored:3/8=38%,added_lines:22/42=52%,removed_lines:14/23=61%,modified commits:3/25=12%)
Randy Dunlap <rdunlap@infradead.org> (commit_signer:2/8=25%,modified commits:3/25=12%)
Bagas Sanjaya <bagasdotme@gmail.com> (commit_signer:1/8=12%,authored:1/8=12%,added_lines:3/42=7%,removed_lines:2/23=9%)
Federico Vaga <federico.vaga@vaga.pv.it> (modified commits:2/25=8%)
linux-doc@vger.kernel.org (open list:DOCUMENTATION)
linux-kernel@vger.kernel.org (open list)

Re: [PATCH v3] Documentation/process: Add text to indicate supporters should be mailed

[Akira Yokosawa]

On Sun, 02 Oct 2022 16:55:05 -0700, Joe Perches wrote:
> On Mon, 2022-10-03 at 08:04 +0900, Akira Yokosawa wrote:
>> Hello Joe,
>>
>> Thank you for chiming in.
>>
>> On 2022/10/03 0:49, Joe Perches wrote:
>>> On Sun, 2022-10-02 at 09:58 +0200, Krzysztof Kozlowski wrote:
>>>> The easiest to achieve it is to run with --no-git-fallback and CC entire
>>>> output. However it does not mean submitter must run with
>>>> --no-git-fallback. It is only for this generic rule - CC entire output
>>>> of get_maintainers.pl.
>>>>
>>>> If you add such rule "CC entire output of get_maintainers.pl" and do not
>>>> mention no-git-fallback, some folks will think they need to CC all these
>>>> people who made one commit to your file...
>>>
>>> false.
>>>
>>> git-fallback is _not_ used when there is a listed maintainer for a
>>> specific file.
>>>
>>> If there is a use of git-fallback, it's because there is _no_
>>> specified maintainer for a specific file.
>>>
>>>    --git-fallback => use git when no exact MAINTAINERS pattern (default: 1)
>>>
>>> i.e.: It's not "your file" if you don't maintain it.
>>
>> Joe, I sometimes see unexpected output WRT --git-fallback.
>>
>> Example:
>>
>>     $ ./get_maintainer.pl -f Documentation/doc-guide/sphinx.rst
>>     Jonathan Corbet <corbet@lwn.net> (maintainer:DOCUMENTATION,commit_signer:1/1=100%)
>>   <-- ???
>>     Lukas Bulwahn <lukas.bulwahn@gmail.com> (commit_signer:1/1=100%,authored:1/1=100%,added_lines:2/2=100%,removed_lines:2/2=100%)
>>     <-- ???
>>     linux-doc@vger.kernel.org (open list:DOCUMENTATION)
>>
>>     linux-kernel@vger.kernel.org (open list)
>>
>> As you see, --git-fallback is used in this case. Why?
>> It looks strange to me as Jon is listed as a "maintainer".
>>
>> Having "F:	Documentation/" in MAINTAINERS does not suffice?
> 
> No.  It's not an exact pattern match as the files below the
> top level of Documentation are not specifically matched by
> "F:	Documentation/".
For me, calling this is "not an exact pattern match" sounds
inconsistent with the explanation (quoted below) near the top of
MAINTAINERS:

	F: *Files* and directories wildcard patterns.
	   A trailing slash includes all files and subdirectory files.

What am I missing?
Does this explanation needs update?

Regards,
Akira

> 
[...]

Re: [PATCH v3] Documentation/process: Add text to indicate supporters should be mailed

[Joe Perches]

On Mon, 2022-10-03 at 10:17 +0900, Akira Yokosawa wrote:
> On Sun, 02 Oct 2022 16:55:05 -0700, Joe Perches wrote:
> > On Mon, 2022-10-03 at 08:04 +0900, Akira Yokosawa wrote:
> > > Hello Joe,
> > > 
> > > Thank you for chiming in.
> > > 
> > > On 2022/10/03 0:49, Joe Perches wrote:
> > > > On Sun, 2022-10-02 at 09:58 +0200, Krzysztof Kozlowski wrote:
> > > > > The easiest to achieve it is to run with --no-git-fallback and CC entire
> > > > > output. However it does not mean submitter must run with
> > > > > --no-git-fallback. It is only for this generic rule - CC entire output
> > > > > of get_maintainers.pl.
> > > > > 
> > > > > If you add such rule "CC entire output of get_maintainers.pl" and do not
> > > > > mention no-git-fallback, some folks will think they need to CC all these
> > > > > people who made one commit to your file...
> > > > 
> > > > false.
> > > > 
> > > > git-fallback is _not_ used when there is a listed maintainer for a
> > > > specific file.
> > > > 
> > > > If there is a use of git-fallback, it's because there is _no_
> > > > specified maintainer for a specific file.
> > > > 
> > > >    --git-fallback => use git when no exact MAINTAINERS pattern (default: 1)
> > > > 
> > > > i.e.: It's not "your file" if you don't maintain it.
> > > 
> > > Joe, I sometimes see unexpected output WRT --git-fallback.
> > > 
> > > Example:
> > > 
> > >     $ ./get_maintainer.pl -f Documentation/doc-guide/sphinx.rst
> > >     Jonathan Corbet <corbet@lwn.net> (maintainer:DOCUMENTATION,commit_signer:1/1=100%)
> > >   <-- ???
> > >     Lukas Bulwahn <lukas.bulwahn@gmail.com> (commit_signer:1/1=100%,authored:1/1=100%,added_lines:2/2=100%,removed_lines:2/2=100%)
> > >     <-- ???
> > >     linux-doc@vger.kernel.org (open list:DOCUMENTATION)
> > > 
> > >     linux-kernel@vger.kernel.org (open list)
> > > 
> > > As you see, --git-fallback is used in this case. Why?
> > > It looks strange to me as Jon is listed as a "maintainer".
> > > 
> > > Having "F:	Documentation/" in MAINTAINERS does not suffice?
> > 
> > No.  It's not an exact pattern match as the files below the
> > top level of Documentation are not specifically matched by
> > "F:	Documentation/".
> For me, calling this is "not an exact pattern match" sounds
> inconsistent with the explanation (quoted below) near the top of
> MAINTAINERS:
> 
> 	F: *Files* and directories wildcard patterns.
> 	   A trailing slash includes all files and subdirectory files.
> What am I missing?
> Does this explanation needs update?

Maybe.  Suggest some text.

Read about the pattern-depth entries (basically, it's the
count of forward slashes '/' in a maintained file pattern)

Look for MAINTAINER entries where there are <foo>/*/ entries too.

For instance:

MAINTAINERS-INTEL ETHERNET DRIVERS
MAINTAINERS-M:  Jesse Brandeburg <jesse.brandeburg@intel.com>
MAINTAINERS-M:  Tony Nguyen <anthony.l.nguyen@intel.com>
MAINTAINERS-L:  intel-wired-lan@lists.osuosl.org (moderated for non-subscribers)
MAINTAINERS-S:  Supported
MAINTAINERS-W:  http://www.intel.com/support/feedback.htm
MAINTAINERS-W:  http://e1000.sourceforge.net/
MAINTAINERS-Q:  http://patchwork.ozlabs.org/project/intel-wired-lan/list/
MAINTAINERS-T:  git git://git.kernel.org/pub/scm/linux/kernel/git/tnguy/net-queue.git
MAINTAINERS-T:  git git://git.kernel.org/pub/scm/linux/kernel/git/tnguy/next-queue.git
MAINTAINERS-F:  Documentation/networking/device_drivers/ethernet/intel/
MAINTAINERS-F:  drivers/net/ethernet/intel/
MAINTAINERS:F:  drivers/net/ethernet/intel/*/     <<< Here >>>
MAINTAINERS-F:  include/linux/avf/virtchnl.h
MAINTAINERS-F:  include/linux/net/intel/iidc.h

So this entry is show that all of drivers/net/ethernet/intel/<foo>/
are directly maintained.

Re: [PATCH v3] Documentation/process: Add text to indicate supporters should be mailed

[Bryan O'Donoghue]

On 30/09/2022 15:47, Akira Yokosawa wrote:
> I guess all you need would be just a short notice along the lines of:
> 
>      "supporter" in the output from get_maintainer.pl means "maintainer
>      of a supported subsystem".
> 
> No?

Oh and I forgot to say, Krzysztof suggesting listing the entire set of 
those who should be mailed and not confining to maintiners and 
supporters only and TBH I think he was right.

Reviewers, sub arch mailing lists, and in some cases LKML are all required.

We should state that more clearly.

---
bod