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

[Joe Perches <joe@perches.com>]

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)