* [PATCH v5 0/1] Fixup instructions around mailing recipients
@ 2022-10-04 12:48 Bryan O'Donoghue
2022-10-04 12:48 ` [PATCH v5 1/1] Documentation/process: Be more explicit about who to mail on patch submission Bryan O'Donoghue
0 siblings, 1 reply; 6+ messages in thread
From: Bryan O'Donoghue @ 2022-10-04 12:48 UTC (permalink / raw)
To: corbet, linux, konstantin, krzysztof.kozlowski, linux-doc, joe, akiyks
Cc: linux-kernel, Bryan O'Donoghue
V5:
- Drops get_maintainer.pl removal of supporter - Joe Perches
- Back to one standalone Documentation change - Krzysztof's suggested list
RESEND:
+ Akira
V4:
- Change the subject line of the series
Previous: Expand get_maintainer to be explicit about supporters
https://lore.kernel.org/all/20220930064629.329514-1-bryan.odonoghue@linaro.org/t/
- Update get_maintainer.pl to return "maintainer" for both "S: Supported"
and "S: Maintained" - Theodore Tso
For the purposes of sending a patch whether or not the maintainer is
listed as volunteer or paid is not really useful information.
Listing both as "maintainer" is clearer the end user.
- Incorporate Krzysztof's list of recipients into
Documentation/process/submitting-patches.rst.
- I didn't include the get_mainainter.pl example.
Comments from both Akira and Joe suggest to me the example is not that
useful.
- get_maintainer will no longer produce "supporter" so one could argue that
the documentation shouldn't refer to supporters however not all of the
potential output strings are documented and I've opted not to document
"chief penguin" either.
I'd like to focus on the particular case of supporters with some
reasonable knock-on documentation tweaks for the obvious gaps we've
identified in our discussion because "supporter" really means
"maintainer" and you absolutely have to mail that person to get your
patch into the right inbox.
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: Be more explicit about who to mail on patch
submission
Documentation/process/submitting-patches.rst | 7 +++++--
1 file changed, 5 insertions(+), 2 deletions(-)
--
2.37.3
^ permalink raw reply [flat|nested] 6+ messages in thread
* [PATCH v5 1/1] Documentation/process: Be more explicit about who to mail on patch submission
2022-10-04 12:48 [PATCH v5 0/1] Fixup instructions around mailing recipients Bryan O'Donoghue
@ 2022-10-04 12:48 ` Bryan O'Donoghue
2022-10-04 15:17 ` Akira Yokosawa
0 siblings, 1 reply; 6+ messages in thread
From: Bryan O'Donoghue @ 2022-10-04 12:48 UTC (permalink / raw)
To: corbet, linux, konstantin, krzysztof.kozlowski, linux-doc, joe, akiyks
Cc: linux-kernel, 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. 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@linaro.org>
---
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@vger.kernel.org should be included. 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
--
2.37.3
^ permalink raw reply related [flat|nested] 6+ messages in thread
* Re: [PATCH v5 1/1] Documentation/process: Be more explicit about who to mail on patch submission
2022-10-04 12:48 ` [PATCH v5 1/1] Documentation/process: Be more explicit about who to mail on patch submission Bryan O'Donoghue
@ 2022-10-04 15:17 ` Akira Yokosawa
2022-10-04 16:27 ` Bryan O'Donoghue
0 siblings, 1 reply; 6+ messages in thread
From: Akira Yokosawa @ 2022-10-04 15:17 UTC (permalink / raw)
To: Bryan O'Donoghue
Cc: linux-kernel, corbet, linux, konstantin, krzysztof.kozlowski,
linux-doc, joe
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@linaro.org>
> ---
> 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@vger.kernel.org should be included. 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
Quoting subsequent paragraph:
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
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?
Doesn't the subsequent paragraph (quoted above) work for you?
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?
Lastly, you submitted v5 within 24 hours from v4. Why so hurry,
especially in the middle of the 6.1 merge window? Actually, as v5
is the same as 2/2 in v4, there was no need of v5 in the first
place.
I'm expecting to see v6 of this patch after the docs-next branch
gets ready for the next development cycle. Until such time comes,
let's continue discussing ideas here in this thread.
Thanks, Akira
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH v5 1/1] Documentation/process: Be more explicit about who to mail on patch submission
2022-10-04 15:17 ` Akira Yokosawa
@ 2022-10-04 16:27 ` Bryan O'Donoghue
2022-10-04 16:38 ` Bryan O'Donoghue
2022-10-06 14:22 ` Akira Yokosawa
0 siblings, 2 replies; 6+ messages in thread
From: Bryan O'Donoghue @ 2022-10-04 16:27 UTC (permalink / raw)
To: Akira Yokosawa
Cc: linux-kernel, corbet, linux, konstantin, krzysztof.kozlowski,
linux-doc, joe
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@linaro.org>
>> ---
>> 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@vger.kernel.org should be included. 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
>
> Quoting subsequent paragraph:
>
> 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
> 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
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH v5 1/1] Documentation/process: Be more explicit about who to mail on patch submission
2022-10-04 16:27 ` Bryan O'Donoghue
@ 2022-10-04 16:38 ` Bryan O'Donoghue
2022-10-06 14:22 ` Akira Yokosawa
1 sibling, 0 replies; 6+ messages in thread
From: Bryan O'Donoghue @ 2022-10-04 16:38 UTC (permalink / raw)
To: Akira Yokosawa
Cc: linux-kernel, corbet, linux, konstantin, krzysztof.kozlowski,
linux-doc, joe
On 04/10/2022 17:27, Bryan O'Donoghue wrote:
> 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.
And similarly, saying in a subsequent paragraph that you should always
mail at last one public mailing list is unnecessarily disregarding
information returned by get_maintainer.
get_maintainer produces a list of text that is very helpful to a
developer in deciding where to send a patch. Documenting that output
directly is a help.
But unless/until get_maintainer is _required_ to be run on any given
patch, then we should still have a standalone paragraph which explicitly
states a public mailing list must receive the patch.
---
bod
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH v5 1/1] Documentation/process: Be more explicit about who to mail on patch submission
2022-10-04 16:27 ` Bryan O'Donoghue
2022-10-04 16:38 ` Bryan O'Donoghue
@ 2022-10-06 14:22 ` Akira Yokosawa
1 sibling, 0 replies; 6+ messages in thread
From: Akira Yokosawa @ 2022-10-06 14:22 UTC (permalink / raw)
To: Bryan O'Donoghue
Cc: linux-kernel, corbet, linux, konstantin, krzysztof.kozlowski,
linux-doc, joe
On Tue, 4 Oct 2022 17:27:06 +0100, Bryan O'Donoghue wrote:
> 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@linaro.org>
>>> ---
>>> 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@vger.kernel.org should be included. 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
>>
>> Quoting subsequent paragraph:
>>
>> 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
>> 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"
Then I think "normally" is the suitable choice because the choice
of recipients is highly dependent of the nature of patches as well
as the subsystem in question.
For example, when submitting an "obviously correct" patch, my list
of CCs could be just:
Cc: Main maintainer of the subsystem in question
Cc: subsystem-specific list
Cc: LKML
, because I can expect the main maintainer would apply it without
any need of someone else's review, and I don't want to spam other
maintainers/reviewers.
On the other hand, when submitting a fix of a regression, my list
of CCs would be:
Cc: Author of the offending commit
Cc: Reviewer A who gave a Reported-by: tag to the offending commit
...
Cc: Maintainer B who is in the Signed-off-by chain of the offending commit
Cc: Maintainer C who is also in the Signed-off-by chain
...
Cc: Main Maintainer of the subsystem in question
Cc: subsystem-specific list
Cc: LKML
When submitting a new version of a patch, in addition to the above,
Cc: Developer D who commented in earlier version(s) of the patch
Cc: Developer E who commented in earlier version(s) of the patch
...
To be clear, I don't use get_maintainer.pl so much for patches to
subsystems I have experience with.
I sometimes try it for unfamiliar area of kernel source tree to know
which subsystem it belongs to.
I'm not sure if this scheme works if I need to submit a patch
to devicetree/media/... where organization of subsystems is complex.
As for submitting-patches.rst, although the expected audience is
inexperienced in submitting patches, it would be safe assume
>
>> 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 might like to be told so, I'd like to know possible options
I can choose.
>
> 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.
You lost me already.
Running get_maintainer is optional, but I must always obey its
suggestion? Huh?
I'm beginning to agree what Jon commented when he applied Krzysztof's patch [1]:
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.
[1]: https://lore.kernel.org/all/87ee12cq2j.fsf@meer.lwn.net/
Bryan, what you are trying here is going to worry Jon further.
I believe this introductory document needs to be kept as concise as
possible.
Documentation on get_maintainer.pl can go elsewhere, and can be as
lengthy as you'd like.
I think I'm not going to do any more review of this kind of change.
Bye.
Akira
>
> ---
> bod
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2022-10-06 14:22 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2022-10-04 12:48 [PATCH v5 0/1] Fixup instructions around mailing recipients Bryan O'Donoghue
2022-10-04 12:48 ` [PATCH v5 1/1] Documentation/process: Be more explicit about who to mail on patch submission Bryan O'Donoghue
2022-10-04 15:17 ` Akira Yokosawa
2022-10-04 16:27 ` Bryan O'Donoghue
2022-10-04 16:38 ` Bryan O'Donoghue
2022-10-06 14:22 ` Akira Yokosawa
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).