[PATCH v2 0/2] Expand get_maintainer to be explicit about supporters

[PATCH v2 0/2] Expand get_maintainer to be explicit about supporters

[Bryan O'Donoghue]

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 (2):
  get_maintainer: Describe supporters and maintainers as required email
    recipients
  Documentation/process: Add text to indicate supporters should be
    mailed

 Documentation/process/submitting-patches.rst | 8 +++++---
 scripts/get_maintainer.pl                    | 4 ++--
 2 files changed, 7 insertions(+), 5 deletions(-)

-- 
2.37.3

[PATCH v2 1/2] get_maintainer: Describe supporters and maintainers as required email recipients

[Bryan O'Donoghue]

The output of get_maintainer.pl doesn't make clear that a supporter is a
type of maintainer who should be mailed when generating a patch.

In various places in the documentation we make reference to the necessity
to remember to include the appropriate maintainers when sending your patch
but, we confusingly don't call out supporters as maintainers in our
automation utility.

Fix that up now by having get_maintainers.pl print 'maintainer[volunteer]'
or 'maintainer[supporter]'.

Suggested-by: Thorsten Leemhuis <linux@leemhuis.info>
Signed-off-by: Bryan O'Donoghue <bryan.odonoghue@linaro.org>
---
 scripts/get_maintainer.pl | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/scripts/get_maintainer.pl b/scripts/get_maintainer.pl
index ab123b498fd9b..f1a081806bf82 100755
--- a/scripts/get_maintainer.pl
+++ b/scripts/get_maintainer.pl
@@ -1283,9 +1283,9 @@ sub get_maintainer_role {
 
     $role = lc($role);
     if      ($role eq "supported") {
-	$role = "supporter";
+	$role = "maintainer[supporter]";
     } elsif ($role eq "maintained") {
-	$role = "maintainer";
+	$role = "maintainer[volunteer]";
     } elsif ($role eq "odd fixes") {
 	$role = "odd fixer";
     } elsif ($role eq "orphan") {
-- 
2.37.3

[PATCH v2 2/2] 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.

Let's add some text to the submitting-patches.rst to indicate that
supporters should similarly be mailed so that you can't do as I did and
mail every maintainer get_maintainer.pl tells you to, without actually
mailing the one supporter you need to.

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

diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
index be49d8f2601b4..aabccaea93375 100644
--- a/Documentation/process/submitting-patches.rst
+++ b/Documentation/process/submitting-patches.rst
@@ -227,9 +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
-(akpm@linux-foundation.org) serves as a maintainer of last resort.
+your patches as arguments to scripts/get_maintainer.pl).  You should mail
+everyone who appears as "maintainer[volunteer]" or "maintainer[supporter]" as
+well as the relevant subsystem mailing list.  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.37.3

Re: [PATCH v2 1/2] get_maintainer: Describe supporters and maintainers as required email recipients

[Theodore Ts'o]

On Thu, Sep 29, 2022 at 01:24:59AM +0100, Bryan O'Donoghue wrote:
> The output of get_maintainer.pl doesn't make clear that a supporter is a
> type of maintainer who should be mailed when generating a patch.
> 
> In various places in the documentation we make reference to the necessity
> to remember to include the appropriate maintainers when sending your patch
> but, we confusingly don't call out supporters as maintainers in our
> automation utility.
> 
> Fix that up now by having get_maintainers.pl print 'maintainer[volunteer]'
> or 'maintainer[supporter]'.

I really don't think this is correct.  Or at least, I don't think it's
consistent with how we've historically understood the S: term in the
MAINTAINERS file.  First of all, the Status field is a property of the
*subsystem*, not of the *maintainer*.

	S: *Status*, one of the following:
	   Supported:	Someone is actually paid to look after this.
	   Maintained:	Someone actually looks after it.
	   Odd Fixes:	It has a maintainer but they don't have time to do
			much other than throw the odd patch in. See below..
	   Orphan:	No current maintainer [but maybe you could take the
			role as you write your new code].
	   Obsolete:	Old code. Something tagged obsolete generally means
			it has been replaced by a better system and you
			should be using that.

There are also plenty of projects which are marked "Maintained" where
one or more the maintainers are paid to support that subsystem (while
others might be volunteers).

So to have get_maintainers.pl print that someone is a
maintainer[volunteer] versus maintainer[supporter] is going to be
highly misleading.  What if one of the maintainers is paid by some
larger company (say, Google or Facebook or Red Hat), while the other
maintainer is a hobbists?  And what for the maintainer who is paid by
a large company, there are multiple levels of "supported".  They might
be allowed to spend up to 50% of the paid time working on upstream
work.  Does that make them a "supported" or a "volunteer"?  And how
should the subsystem's S: be marked?

I understand that get_maintinaer.pl has had this get_maintainer_role
function for a long time; it's not been introduced by this patch.  But
I'd suggest that we not try to make a distinction between a subsystem
which is "Supported" versus "Maintained", and certainly we should not
be treating an attribute of the subsystem as being attached to all of
the entities listed under M:.  That is really a category error, IMHO.

    	     	    	       	       - Ted

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

[Krzysztof Kozlowski]

On 29/09/2022 02:25, 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.
> 
> Let's add some text to the submitting-patches.rst to indicate that
> supporters should similarly be mailed so that you can't do as I did and
> mail every maintainer get_maintainer.pl tells you to, without actually
> mailing the one supporter you need to.
> 
> Signed-off-by: Bryan O'Donoghue <bryan.odonoghue@linaro.org>
> ---
>  Documentation/process/submitting-patches.rst | 8 +++++---
>  1 file changed, 5 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
> index be49d8f2601b4..aabccaea93375 100644
> --- a/Documentation/process/submitting-patches.rst
> +++ b/Documentation/process/submitting-patches.rst
> @@ -227,9 +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
> -(akpm@linux-foundation.org) serves as a maintainer of last resort.
> +your patches as arguments to scripts/get_maintainer.pl).  You should mail
> +everyone who appears as "maintainer[volunteer]" or "maintainer[supporter]" as

As I said before, this still ignores reviewers. I don't think it is
going to good direction. The submitter is expected to CC
everyone/everything which is pointed by get_maintainers.pl except the
Git-fallback entries.

Best regards,
Krzysztof

Re: [PATCH v2 1/2] get_maintainer: Describe supporters and maintainers as required email recipients

[Thorsten Leemhuis]

On 29.09.22 05:29, Theodore Ts'o wrote:
> On Thu, Sep 29, 2022 at 01:24:59AM +0100, Bryan O'Donoghue wrote:
>> The output of get_maintainer.pl doesn't make clear that a supporter is a
>> type of maintainer who should be mailed when generating a patch.
>>
>> In various places in the documentation we make reference to the necessity
>> to remember to include the appropriate maintainers when sending your patch
>> but, we confusingly don't call out supporters as maintainers in our
>> automation utility.
>>
>> Fix that up now by having get_maintainers.pl print 'maintainer[volunteer]'
>> or 'maintainer[supporter]'.
> 
> I really don't think this is correct.  Or at least, I don't think it's
> consistent with how we've historically understood the S: term in the
> MAINTAINERS file. [...]

Hmm, yeah, you are right, I didn't think this trough when suggesting
"maintainer[volunteer]". @Bryan: sorry for leading your in the wrong
direction.

Ciao, Thorsten

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

[Bryan O'Donoghue]

On 29/09/2022 08:29, Krzysztof Kozlowski wrote:
> As I said before, this still ignores reviewers. I don't think it is
> going to good direction. The submitter is expected to CC
> everyone/everything which is pointed by get_maintainers.pl except the
> Git-fallback entries.

Isn't LKML considered optional at this point though ?

---
bod

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

[Bryan O'Donoghue]

On 29/09/2022 08:29, Krzysztof Kozlowski wrote:
> On 29/09/2022 02:25, 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.
>>
>> Let's add some text to the submitting-patches.rst to indicate that
>> supporters should similarly be mailed so that you can't do as I did and
>> mail every maintainer get_maintainer.pl tells you to, without actually
>> mailing the one supporter you need to.
>>
>> Signed-off-by: Bryan O'Donoghue <bryan.odonoghue@linaro.org>
>> ---
>>   Documentation/process/submitting-patches.rst | 8 +++++---
>>   1 file changed, 5 insertions(+), 3 deletions(-)
>>
>> diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
>> index be49d8f2601b4..aabccaea93375 100644
>> --- a/Documentation/process/submitting-patches.rst
>> +++ b/Documentation/process/submitting-patches.rst
>> @@ -227,9 +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
>> -(akpm@linux-foundation.org) serves as a maintainer of last resort.
>> +your patches as arguments to scripts/get_maintainer.pl).  You should mail
>> +everyone who appears as "maintainer[volunteer]" or "maintainer[supporter]" as
> 
> As I said before, this still ignores reviewers. I don't think it is
> going to good direction. The submitter is expected to CC
> everyone/everything which is pointed by get_maintainers.pl except the
> Git-fallback entries.


I just found the --nogit-fallback option which produces:

scripts/get_maintainer.pl Documentation/process/submitting-patches.rst
Jonathan Corbet <corbet@lwn.net> 
(maintainer:DOCUMENTATION,commit_signer:10/12=83%)
Konstantin Ryabitsev <konstantin@linuxfoundation.org> 
(commit_signer:2/12=17%)
Thorsten Leemhuis <linux@leemhuis.info> 
(commit_signer:2/12=17%,authored:2/12=17%,added_lines:24/46=52%,removed_lines:13/67=19%)
Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> 
(commit_signer:2/12=17%,authored:2/12=17%,added_lines:8/46=17%,removed_lines:4/67=6%)
Randy Dunlap <rdunlap@infradead.org> (commit_signer:2/12=17%)
"Bryan O'Donoghue" <bryan.odonoghue@linaro.org> 
(authored:1/12=8%,added_lines:5/46=11%)
Erik Ekman <erik@kryo.se> (authored:1/12=8%)
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> (authored:1/12=8%)
Jiri Kosina <jkosina@suse.cz> (removed_lines:20/67=30%)
Miguel Ojeda <ojeda@kernel.org> (removed_lines:19/67=28%)
linux-doc@vger.kernel.org (open list:DOCUMENTATION)
linux-kernel@vger.kernel.org (open list)

scripts/get_maintainer.pl --status --nom --nol --nogit --nogit-fallback 
-f Documentation/process/submitting-patches.rst

How about something like "send email to every mail address produced by 
scripts/get_maintainer.pl $filename but consider linux-kernel optional 
when sending subsystem specific patches"

---
bod

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

[Krzysztof Kozlowski]

On 29/09/2022 12:33, Bryan O'Donoghue wrote:
> On 29/09/2022 08:29, Krzysztof Kozlowski wrote:
>> As I said before, this still ignores reviewers. I don't think it is
>> going to good direction. The submitter is expected to CC
>> everyone/everything which is pointed by get_maintainers.pl except the
>> Git-fallback entries.
> 
> Isn't LKML considered optional at this point though ?

No, it's the only list for certain subsystems. If you do not cc it, the
patch might never get public.

Best regards,
Krzysztof