[PATCH] Documentation/process: use scripts/get_maintainer.pl on patches

[PATCH] Documentation/process: use scripts/get_maintainer.pl on patches

[Krzysztof Kozlowski]

Explain that, when collecting list of people to Cc the patch,
scripts/get_maintainer.pl should be used on patches, not on the
directories.  The behavior is quite different, because with "-f" on
a directory, the maintainers of individual files will not be shown.

Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>

---

It seems using the script on patches is not obvious and it already
caused some misunderstandings.
---
 Documentation/doc-guide/contributing.rst     | 5 +++--
 Documentation/process/3.Early-stage.rst      | 9 +++++----
 Documentation/process/submitting-patches.rst | 7 ++++---
 3 files changed, 12 insertions(+), 9 deletions(-)

diff --git a/Documentation/doc-guide/contributing.rst b/Documentation/doc-guide/contributing.rst
index 207fd93d7c80..d4793826ad9a 100644
--- a/Documentation/doc-guide/contributing.rst
+++ b/Documentation/doc-guide/contributing.rst
@@ -79,8 +79,9 @@ simplistic idea of what C comment blocks look like.  This problem had been
 present since that comment was added in 2016 — a full four years.  Fixing
 it was a matter of adding the missing asterisks.  A quick look at the
 history for that file showed what the normal format for subject lines is,
-and ``scripts/get_maintainer.pl`` told me who should receive it.  The
-resulting patch looked like this::
+and ``scripts/get_maintainer.pl`` told me who should receive it (pass paths to
+your patches as arguments to scripts/get_maintainer.pl).  The resulting patch
+looked like this::
 
   [PATCH] PM / devfreq: Fix two malformed kerneldoc comments
 
diff --git a/Documentation/process/3.Early-stage.rst b/Documentation/process/3.Early-stage.rst
index 6bfd60d77d1a..894a920041c6 100644
--- a/Documentation/process/3.Early-stage.rst
+++ b/Documentation/process/3.Early-stage.rst
@@ -154,10 +154,11 @@ that the kernel developers have added a script to ease the process:
 This script will return the current maintainer(s) for a given file or
 directory when given the "-f" option.  If passed a patch on the
 command line, it will list the maintainers who should probably receive
-copies of the patch.  There are a number of options regulating how hard
-get_maintainer.pl will search for maintainers; please be careful about
-using the more aggressive options as you may end up including developers
-who have no real interest in the code you are modifying.
+copies of the patch.  This is the preferred way (unlike "-f" option) to get the
+list of people to Cc for your patches.  There are a number of options
+regulating how hard get_maintainer.pl will search for maintainers; please be
+careful about using the more aggressive options as you may end up including
+developers who have no real interest in the code you are modifying.
 
 If all else fails, talking to Andrew Morton can be an effective way to
 track down a maintainer for a specific piece of code.
diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
index 9bb4e8c0f635..1708b66c4672 100644
--- a/Documentation/process/submitting-patches.rst
+++ b/Documentation/process/submitting-patches.rst
@@ -227,9 +227,10 @@ Select the recipients for your patch
 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.  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.
+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.
 
 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.32.0

Re: [PATCH] Documentation/process: use scripts/get_maintainer.pl on patches

[Bagas Sanjaya]

On 4/28/22 01:56, Krzysztof Kozlowski wrote:
> diff --git a/Documentation/process/3.Early-stage.rst b/Documentation/process/3.Early-stage.rst
> index 6bfd60d77d1a..894a920041c6 100644
> --- a/Documentation/process/3.Early-stage.rst
> +++ b/Documentation/process/3.Early-stage.rst
> @@ -154,10 +154,11 @@ that the kernel developers have added a script to ease the process:
>  This script will return the current maintainer(s) for a given file or
>  directory when given the "-f" option.  If passed a patch on the
>  command line, it will list the maintainers who should probably receive
> -copies of the patch.  There are a number of options regulating how hard
> -get_maintainer.pl will search for maintainers; please be careful about
> -using the more aggressive options as you may end up including developers
> -who have no real interest in the code you are modifying.
> +copies of the patch.  This is the preferred way (unlike "-f" option) to get the
> +list of people to Cc for your patches.  There are a number of options
> +regulating how hard get_maintainer.pl will search for maintainers; please be
> +careful about using the more aggressive options as you may end up including
> +developers who have no real interest in the code you are modifying.
>  

This raises my question: Supposed that I'm ready to send multiple-patch
series (two or more patches in the series). How can I get maintainers list,
given such series?

-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH] Documentation/process: use scripts/get_maintainer.pl on patches

[Krzysztof Kozlowski]

On 28/04/2022 07:42, Bagas Sanjaya wrote:
> On 4/28/22 01:56, Krzysztof Kozlowski wrote:
>> diff --git a/Documentation/process/3.Early-stage.rst b/Documentation/process/3.Early-stage.rst
>> index 6bfd60d77d1a..894a920041c6 100644
>> --- a/Documentation/process/3.Early-stage.rst
>> +++ b/Documentation/process/3.Early-stage.rst
>> @@ -154,10 +154,11 @@ that the kernel developers have added a script to ease the process:
>>  This script will return the current maintainer(s) for a given file or
>>  directory when given the "-f" option.  If passed a patch on the
>>  command line, it will list the maintainers who should probably receive
>> -copies of the patch.  There are a number of options regulating how hard
>> -get_maintainer.pl will search for maintainers; please be careful about
>> -using the more aggressive options as you may end up including developers
>> -who have no real interest in the code you are modifying.
>> +copies of the patch.  This is the preferred way (unlike "-f" option) to get the
>> +list of people to Cc for your patches.  There are a number of options
>> +regulating how hard get_maintainer.pl will search for maintainers; please be
>> +careful about using the more aggressive options as you may end up including
>> +developers who have no real interest in the code you are modifying.
>>  
> 
> This raises my question: Supposed that I'm ready to send multiple-patch
> series (two or more patches in the series). How can I get maintainers list,
> given such series?

Method is the same, nothing differs. What is inaccurate in my
description above around such case?

Best regards,
Krzysztof

Re: [PATCH] Documentation/process: use scripts/get_maintainer.pl on patches

[Jonathan Corbet]

Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> writes:

> Explain that, when collecting list of people to Cc the patch,
> scripts/get_maintainer.pl should be used on patches, not on the
> directories.  The behavior is quite different, because with "-f" on
> a directory, the maintainers of individual files will not be shown.
>
> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
>
> ---
>
> It seems using the script on patches is not obvious and it already
> caused some misunderstandings.
> ---
>  Documentation/doc-guide/contributing.rst     | 5 +++--
>  Documentation/process/3.Early-stage.rst      | 9 +++++----
>  Documentation/process/submitting-patches.rst | 7 ++++---
>  3 files changed, 12 insertions(+), 9 deletions(-)

I worry about trying to cram every detail into these documents; it's not
as if their length isn't intimidating already.  But I've gone ahead and
applied this, thanks.

jon