[RFC] docs: process: Send patches 'To' maintainers and 'Cc' lists

[RFC] docs: process: Send patches 'To' maintainers and 'Cc' lists

[James Seo]

The existing wording in the 'Select the recipients for your patch'
section of submitting-patches.rst states that contributors should
'copy' maintainers and lists, which might be interpreted to mean that
patch e-mails should be sent 'Cc' such recipients without any 'To'
recipients at all.

Indeed, this does happen on occasion (and to be fair, examples of the
practice predating the submitting-patches document exist in kernel
mailing list archives). It isn't a problem on the protocol level, as
SMTP itself deals only with SMTP commands (cf. 'RCPT TO'), but
software that works with MIME headers in message text, perhaps in
order to generate those commands, doesn't always handle the situation
well.

At present, when such an e-mail is sent to the vger listservs, the
MIME header 'To: unlisted-recipients:; (no To-header on input)' is
added to it somewhere along the chain. 'unlisted-recipients:;' is a
valid RFC 5322 Group Address, but it (or '(no To-header on input)')
sometimes goes on to cause problems itself further down the line.

For example, in mutt, it can result in the silent removal of all 'Cc'
recipients (e.g. kernel mailing lists) from a group reply, leaving
the 'To' recipient that the original e-mail was 'From' as the only
actual reply recipient [1]. Other issues [2] are possible in other
software [3]. It also bears mentioning that a lack of 'To' headers is
a characteristic of some spam, so such an e-mail may trigger some
spam filters.

To reduce ambiguity and eliminate this class of potential (albeit
tangential) issues, prescribe sending patches 'To' maintainers and
'Cc' lists. While we're at it, strengthen the recommendation to use
scripts/get_maintainer.pl to find patch recipients, and move Andrew
Morton's callout as the maintainer of last resort to the next
paragraph for better flow.

Link: https://github.com/neomutt/neomutt/issues/2548 [1]
Link: https://github.com/python/cpython/issues/83281 [2]
Link: https://github.com/kvalo/pwcli/issues/15 [3]
Signed-off-by: James Seo <james@equiv.tech>
---
 Documentation/process/submitting-patches.rst | 17 +++++++++--------
 1 file changed, 9 insertions(+), 8 deletions(-)

diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
index efac910e2659..53460f3cdc1d 100644
--- a/Documentation/process/submitting-patches.rst
+++ b/Documentation/process/submitting-patches.rst
@@ -231,14 +231,15 @@ patch.
 Select the recipients for your patch
 ------------------------------------
 
-You should always copy the appropriate subsystem maintainer(s) and list(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.
-
+You should always notify the appropriate subsystem maintainer(s) and list(s)
+about any patch to code that they maintain.  Identify them by looking through
+the MAINTAINERS file and the source code revision history, and by using the
+script scripts/get_maintainer.pl (pass paths to your patches as arguments to
+scripts/get_maintainer.pl).  Send your patch e-mail "To:" those maintainers and
+"Cc:" those lists.
+
+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.  Also,
 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.  Please
 do not spam unrelated lists and unrelated people, though.
-- 
2.39.2

Re: [RFC] docs: process: Send patches 'To' maintainers and 'Cc' lists

[Randy Dunlap]

Hi--

On 6/3/23 08:14, James Seo wrote:
> The existing wording in the 'Select the recipients for your patch'
> section of submitting-patches.rst states that contributors should
> 'copy' maintainers and lists, which might be interpreted to mean that
> patch e-mails should be sent 'Cc' such recipients without any 'To'
> recipients at all.
> 
> Indeed, this does happen on occasion (and to be fair, examples of the
> practice predating the submitting-patches document exist in kernel
> mailing list archives). It isn't a problem on the protocol level, as
> SMTP itself deals only with SMTP commands (cf. 'RCPT TO'), but
> software that works with MIME headers in message text, perhaps in
> order to generate those commands, doesn't always handle the situation
> well.
> 
> At present, when such an e-mail is sent to the vger listservs, the
> MIME header 'To: unlisted-recipients:; (no To-header on input)' is
> added to it somewhere along the chain. 'unlisted-recipients:;' is a
> valid RFC 5322 Group Address, but it (or '(no To-header on input)')
> sometimes goes on to cause problems itself further down the line.
> 
> For example, in mutt, it can result in the silent removal of all 'Cc'
> recipients (e.g. kernel mailing lists) from a group reply, leaving
> the 'To' recipient that the original e-mail was 'From' as the only
> actual reply recipient [1]. Other issues [2] are possible in other
> software [3]. It also bears mentioning that a lack of 'To' headers is
> a characteristic of some spam, so such an e-mail may trigger some
> spam filters.

It sounds to me like we should just prohibit (not allow) emails that
don't have a To: recipient in them. It also sounds like mutt (and maybe
other software) have problems.

Is that something that vger could do?  (although we have other
email servers as well, e.g., infradead).

> To reduce ambiguity and eliminate this class of potential (albeit
> tangential) issues, prescribe sending patches 'To' maintainers and
> 'Cc' lists. While we're at it, strengthen the recommendation to use
> scripts/get_maintainer.pl to find patch recipients, and move Andrew
> Morton's callout as the maintainer of last resort to the next
> paragraph for better flow.
> 

I think that is going overboard (too far). As long as a maintainer
is a direct recipient of the email (patch), that should be sufficient.

> Link: https://github.com/neomutt/neomutt/issues/2548 [1]
> Link: https://github.com/python/cpython/issues/83281 [2]
> Link: https://github.com/kvalo/pwcli/issues/15 [3]
> Signed-off-by: James Seo <james@equiv.tech>
> ---
>  Documentation/process/submitting-patches.rst | 17 +++++++++--------
>  1 file changed, 9 insertions(+), 8 deletions(-)
> 
> diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
> index efac910e2659..53460f3cdc1d 100644
> --- a/Documentation/process/submitting-patches.rst
> +++ b/Documentation/process/submitting-patches.rst
> @@ -231,14 +231,15 @@ patch.
>  Select the recipients for your patch
>  ------------------------------------
>  
> -You should always copy the appropriate subsystem maintainer(s) and list(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.
> -
> +You should always notify the appropriate subsystem maintainer(s) and list(s)
> +about any patch to code that they maintain.  Identify them by looking through
> +the MAINTAINERS file and the source code revision history, and by using the
> +script scripts/get_maintainer.pl (pass paths to your patches as arguments to
> +scripts/get_maintainer.pl).  Send your patch e-mail "To:" those maintainers and
> +"Cc:" those lists.
> +
> +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.  Also,
>  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.  Please
>  do not spam unrelated lists and unrelated people, though.

-- 
~Randy

Re: [RFC] docs: process: Send patches 'To' maintainers and 'Cc' lists

[Willy Tarreau]

Hi Randy,

On Sat, Jun 03, 2023 at 08:55:39AM -0700, Randy Dunlap wrote:
> It sounds to me like we should just prohibit (not allow) emails that
> don't have a To: recipient in them.

Also those without subjects, which seem to become increasingly frequent
and which used to exclusively be used by spam years ago.

> > To reduce ambiguity and eliminate this class of potential (albeit
> > tangential) issues, prescribe sending patches 'To' maintainers and
> > 'Cc' lists. While we're at it, strengthen the recommendation to use
> > scripts/get_maintainer.pl to find patch recipients, and move Andrew
> > Morton's callout as the maintainer of last resort to the next
> > paragraph for better flow.
> > 
> 
> I think that is going overboard (too far). As long as a maintainer
> is a direct recipient of the email (patch), that should be sufficient.

Or it could be simplified, saying that all those who are expected to
play a role on the patchset (review, test, merge etc) should be in the
'To' field while those who might possibly be interested in having a
look are in 'Cc' (lists, other people having expressed interest in the
patchset, single-time contributors to the file being changed etc). It
could be hinted that usually people read mails sent to them faster than
those they're CCed. This implies that maintainers have to be in To and
lists in Cc.

regards,
Willy

Re: [RFC] docs: process: Send patches 'To' maintainers and 'Cc' lists

[Bagas Sanjaya]

On 6/3/23 22:55, Randy Dunlap wrote:
> It sounds to me like we should just prohibit (not allow) emails that
> don't have a To: recipient in them. It also sounds like mutt (and maybe
> other software) have problems.
> 

In mutt, there is a command for reply-to-all (named group-chat-reply),
but you need to assign key binding for it. I'd like to type Esc-g
for this purpose. The corresponding .muttrc is:

```
bind index,pager "<esc>g" group-chat-reply
```

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

Re: [RFC] docs: process: Send patches 'To' maintainers and 'Cc' lists

[Bagas Sanjaya]

On 6/3/23 22:14, James Seo wrote:
> To reduce ambiguity and eliminate this class of potential (albeit
> tangential) issues, prescribe sending patches 'To' maintainers and
> 'Cc' lists. While we're at it, strengthen the recommendation to use
> scripts/get_maintainer.pl to find patch recipients, and move Andrew
> Morton's callout as the maintainer of last resort to the next
> paragraph for better flow.
> 

IMO, To: and Cc: don't have any practical differences between two,
and I usually do vice-versa when sending patches: lists are in To:
and individual maintainers are in Cc:

Thanks.

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

Re: [RFC] docs: process: Send patches 'To' maintainers and 'Cc' lists

[Jakub Kicinski]

On Sat, 3 Jun 2023 18:06:59 +0200 Willy Tarreau wrote:
> > I think that is going overboard (too far). As long as a maintainer
> > is a direct recipient of the email (patch), that should be sufficient.  
> 
> Or it could be simplified, saying that all those who are expected to
> play a role on the patchset (review, test, merge etc) should be in the
> 'To' field while those who might possibly be interested in having a
> look are in 'Cc' (lists, other people having expressed interest in the
> patchset, single-time contributors to the file being changed etc). It
> could be hinted that usually people read mails sent to them faster than
> those they're CCed. This implies that maintainers have to be in To and
> lists in Cc.

It's useful when maintainer (or group thereof) who are expected to apply
the patch are in the To:
Who applies the patch is not information a noob may know but it may be
worth writing down as best practice?

Re: [RFC] docs: process: Send patches 'To' maintainers and 'Cc' lists

[Jakub Kicinski]

On Sat,  3 Jun 2023 08:14:47 -0700 James Seo wrote:
> +You should always notify the appropriate subsystem maintainer(s) and list(s)

s/notify/specify as recipients/ ?
notify sounds like an out of band ping, maybe just to me.

> +about any patch to code that they maintain.  Identify them by looking through
> +the MAINTAINERS file and the source code revision history, and by using the
> +script scripts/get_maintainer.pl (pass paths to your patches as arguments to
> +scripts/get_maintainer.pl).  Send your patch e-mail "To:" those maintainers and
> +"Cc:" those lists.

There's a handful of people who run get_maintainer on the file paths,

 ./scripts/get_maintainer.pl net/core/dev.c
rather than
 ./scripts/get_maintainer.pl 0001-my.patch

This leads to ignoring Fixes tags, and authors of fixed commits should
really be CCed.

Since we're touching this paragraph maybe we can massage the wording 
a bit:

(pass paths to your patches generated by git format-patch 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.  Also,

Thanks for the patch, btw, we also see To-less patches a couple times 
a month on netdev@ :(

Re: [RFC] docs: process: Send patches 'To' maintainers and 'Cc' lists

[Randy Dunlap]

On 6/4/23 07:01, Bagas Sanjaya wrote:
> On 6/3/23 22:14, James Seo wrote:
>> To reduce ambiguity and eliminate this class of potential (albeit
>> tangential) issues, prescribe sending patches 'To' maintainers and
>> 'Cc' lists. While we're at it, strengthen the recommendation to use
>> scripts/get_maintainer.pl to find patch recipients, and move Andrew
>> Morton's callout as the maintainer of last resort to the next
>> paragraph for better flow.
>>
> 
> IMO, To: and Cc: don't have any practical differences between two,
> and I usually do vice-versa when sending patches: lists are in To:
> and individual maintainers are in Cc:

Ack all of that.

-- 
~Randy

Re: [RFC] docs: process: Send patches 'To' maintainers and 'Cc' lists

[Laurent Pinchart]

On Sun, Jun 04, 2023 at 11:26:44AM -0700, Jakub Kicinski wrote:
> On Sat, 3 Jun 2023 18:06:59 +0200 Willy Tarreau wrote:
> > > I think that is going overboard (too far). As long as a maintainer
> > > is a direct recipient of the email (patch), that should be sufficient.  
> > 
> > Or it could be simplified, saying that all those who are expected to
> > play a role on the patchset (review, test, merge etc) should be in the
> > 'To' field while those who might possibly be interested in having a
> > look are in 'Cc' (lists, other people having expressed interest in the
> > patchset, single-time contributors to the file being changed etc). It
> > could be hinted that usually people read mails sent to them faster than
> > those they're CCed. This implies that maintainers have to be in To and
> > lists in Cc.
> 
> It's useful when maintainer (or group thereof) who are expected to apply
> the patch are in the To:
> Who applies the patch is not information a noob may know but it may be
> worth writing down as best practice?

Note that some maintainers process pull requests from patchwork, not
from their mailbox, and prefer not to be aadressed in the To or CC
headers. I don't know how widespread that is. If I recall correctly,
this was something that maintainer profiles
(maintainer-entry-profile.rst files in Documentation) were supposed to
address.

-- 
Regards,

Laurent Pinchart

Re: [RFC] docs: process: Send patches 'To' maintainers and 'Cc' lists

[Kalle Valo]

Laurent Pinchart <laurent.pinchart@ideasonboard.com> writes:

> On Sun, Jun 04, 2023 at 11:26:44AM -0700, Jakub Kicinski wrote:
>> On Sat, 3 Jun 2023 18:06:59 +0200 Willy Tarreau wrote:
>> > > I think that is going overboard (too far). As long as a maintainer
>> > > is a direct recipient of the email (patch), that should be sufficient.  
>> > 
>> > Or it could be simplified, saying that all those who are expected to
>> > play a role on the patchset (review, test, merge etc) should be in the
>> > 'To' field while those who might possibly be interested in having a
>> > look are in 'Cc' (lists, other people having expressed interest in the
>> > patchset, single-time contributors to the file being changed etc). It
>> > could be hinted that usually people read mails sent to them faster than
>> > those they're CCed. This implies that maintainers have to be in To and
>> > lists in Cc.
>> 
>> It's useful when maintainer (or group thereof) who are expected to apply
>> the patch are in the To:
>> Who applies the patch is not information a noob may know but it may be
>> worth writing down as best practice?
>
> Note that some maintainers process pull requests from patchwork, not
> from their mailbox, and prefer not to be aadressed in the To or CC
> headers. I don't know how widespread that is.

FWIW I belong to this group and prefer not be in To or Cc, I'll always
check the patch from patchwork.

-- 
https://patchwork.kernel.org/project/linux-wireless/list/

https://wireless.wiki.kernel.org/en/developers/documentation/submittingpatches

Re: [RFC] docs: process: Send patches 'To' maintainers and 'Cc' lists

[Jakub Kicinski]

On Mon, 05 Jun 2023 16:22:46 +0300 Kalle Valo wrote:
> > Note that some maintainers process pull requests from patchwork, not
> > from their mailbox, and prefer not to be aadressed in the To or CC
> > headers. I don't know how widespread that is.  
> 
> FWIW I belong to this group and prefer not be in To or Cc, I'll always
> check the patch from patchwork.

Ah, I didn't realize this. 

Re: [RFC] docs: process: Send patches 'To' maintainers and 'Cc' lists

[Kalle Valo]

Jakub Kicinski <kuba@kernel.org> writes:

> On Mon, 05 Jun 2023 16:22:46 +0300 Kalle Valo wrote:
>> > Note that some maintainers process pull requests from patchwork, not
>> > from their mailbox, and prefer not to be aadressed in the To or CC
>> > headers. I don't know how widespread that is.  
>> 
>> FWIW I belong to this group and prefer not be in To or Cc, I'll always
>> check the patch from patchwork.
>
> Ah, I didn't realize this. 

So no action needed for this, I'm sure I'm in a very small minority and
I can handle the mails with my filters just fine. Just wanted to comment
that such maintainers do exist.

-- 
https://patchwork.kernel.org/project/linux-wireless/list/

https://wireless.wiki.kernel.org/en/developers/documentation/submittingpatches