| Message ID | 20210512025447.6068-1-dwh@linuxprogrammer.org (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | [v1] Writing down mail list etiquette. | expand |
Doh! I forgot to make this patch In-Reply-To the previous thread that sparked this discussion. Well, at least this patch email doesn't have a Mail-Followup-To header. Cheers! Dave
Aaaand I forgot to Cc all of the relevant people from the previous thread. I also messed up a name and email in the previous commit messages. Both are fixed. It's been a long day :) Cheers! Dave
Dave Huseby wrote: > After violating a few unspoken etiquette rules that were spotted by > Christian Couder <christian.couder@gmail.com>, Filipe Contreras > <felipe.contreras@gmail.com> suggested that somebody write a guide. Thanks for doing this. It's hard for seasoned developers to spot the gaps in documentation, and that's why it's so important for newcomers to fill them before they themselve get too accustomed with the project. > --- /dev/null > +++ b/Documentation/MailingListEtiquette.txt > @@ -0,0 +1,125 @@ > +Mailing List Etiquette > +====================== > + > +[[introduction]] > +== Introduction > + > +Open source, community projects such as Git use a mailing list and email to > +coordinate development and to submit patches for review. This article documents > +the unspoken rules and etiquette for the proper way to send email to the > +mailing list. What follows are considered best practices to follow. Some open source projects--such as Git--use email to... Some open source projects do, certainly not all. > +If you are looking for details on how to submit a patch, that is documented > +elsewhere in: > + > +- `Documentation/SubmittingPatches` > +- `Documentation/MyFirstContribution.txt` > + > +[[proper-use-of-to-and-cc]] > +== Proper Use of To and Cc > + > +When starting a new email thread that is not directed at any specific person, > +put the mailing list address in the "To:" field, otherwise address it to the > +person and put the mailing list address in the "Cc:" field. > + > +When replying to an email on the mailing list, put the person you are replying > +to in the "To:" field and all other people in the thread in the "Cc:" field, > +including the mailing list address. > + > +Make sure to keep everyone involved in the "Cc:" field so that they do not have > +to be subscribed to the mailing list to receive replies. Although all this is OK, I don't think it matters much who you put in Cc, and who in the To fields. As long as everyone involved--including the mailing list--is in both fields, you are fine. > +[[do-not-use-mail-followup-to]] > +== Do Not Use Mail-Followup-To Er, this is improtant, but it shouldn't be #2. There's a lot of things more important than this, for example something I encountered recently... Do not top-post [1], and try to remove as much context as possible. Only leave the context that is important for your reply. In fact, this opens the possiblity for some much needed levity... A: Because it messes up the order in which people normally read text. Q: Why is top-posting such a bad thing? A: Top-posting. Q: What is the most annoying thing in e-mail? This is especially important for people coming from corporate environments where top-posting is the norm, and no context is ever deleted. [1] https://en.wikipedia.org/wiki/Posting_style#Interleaved_style > +[[enable-plain-text-mode]] > +== Enable Plain Text Mode > + > +Most email clients automatically reject mailing list email if it is not a > +text/plain formatted email. It's not the email clients, it's the mailing list software itself. Either way this is important. > +[[patches-that-receive-no-response]] > + > +From Junio's notes from the maintainer: > + > +> If you sent a patch and you did not hear any response from anybody for > +> several days, it could be that your patch was totally uninteresting, > +> but it also is possible that it was simply lost in the noise. Please > +> do not hesitate to send a reminder message in such a case. Messages > +> getting lost in the noise may be a sign that those who can evaluate > +> your patch don't have enough mental/time bandwidth to process them > +> right at the moment, and it often helps to wait until the list traffic > +> becomes calmer before sending such a reminder. This is important for other mails, like bug reports, and questions, not just patches. Another very general aspect of the git mailing list (and others similar), is that you should never be afraid of simply sending a point-blank mail to the mailinsg list. You don't need to subscribe, and you don't need to look for people to Cc... Just send the mail. It's generally better to just send the mail than not send it (even if people like Dave are bitten by their configuration). Cheers.
Dave Huseby wrote: > Doh! I forgot to make this patch In-Reply-To the previous thread that > sparked this discussion. Well, at least this patch email doesn't have a > Mail-Followup-To header. Ahh, that reminds me of another point I wanted to raise. In general people should try to start new threads rather than recycle old ones (unless specifically necessary). I suspect this is contentious at this point, but I personally belive this is the way to go. If people align with my view, then you did the correct thing by starting a new thread rather than using In-Reply-To. We'll see.
On 12/05/2021 04:18, Dave Huseby wrote: > Aaaand I forgot to Cc all of the relevant people from the previous > thread. I also messed up a name and email in the previous commit > messages. Both are fixed. It's been a long day :) > > Cheers! > Dave > And try to ensure the subject is carried in the replies, to avoid deletion as 'junk/spam' (not sure how it happened, just sayin'). I'd hesitated to open the email because of the blank subject. Also add a note about how to update a subject when a thread has diverged, e.g. "Diverged thread (was: Writing down mail list etiquette)." Philip
diff --git a/Documentation/MailingListEtiquette.txt b/Documentation/MailingListEtiquette.txt new file mode 100644 index 0000000000..9da2d490aa --- /dev/null +++ b/Documentation/MailingListEtiquette.txt @@ -0,0 +1,125 @@ +Mailing List Etiquette +====================== + +[[introduction]] +== Introduction + +Open source, community projects such as Git use a mailing list and email to +coordinate development and to submit patches for review. This article documents +the unspoken rules and etiquette for the proper way to send email to the +mailing list. What follows are considered best practices to follow. + +If you are looking for details on how to submit a patch, that is documented +elsewhere in: + +- `Documentation/SubmittingPatches` +- `Documentation/MyFirstContribution.txt` + +[[proper-use-of-to-and-cc]] +== Proper Use of To and Cc + +When starting a new email thread that is not directed at any specific person, +put the mailing list address in the "To:" field, otherwise address it to the +person and put the mailing list address in the "Cc:" field. + +When replying to an email on the mailing list, put the person you are replying +to in the "To:" field and all other people in the thread in the "Cc:" field, +including the mailing list address. + +Make sure to keep everyone involved in the "Cc:" field so that they do not have +to be subscribed to the mailing list to receive replies. + +[[do-not-use-mail-followup-to]] +== Do Not Use Mail-Followup-To + +When posting to the mailing list, your email client might add a +"Mail-Followup-To:" field which contains all of the recipients, including the +mailing list address, but not the sender's email address. This is intended to +prevent the sender from receiving replies twice, once from the replying person +and again from the mailing list. + +This goes directly against the desired "To:" and "Cc:" etiquette (see "Proper +Use of To and Cc" above). Most users want to use "group reply" or "Reply to +all" in their mail client and create a reply email that is sent directly to +author of the email they are replying to with all other recipients, as well as +the mailing list address, in the "Cc:" field. + +The proper thing to do is to never use the "Mail-Followup-To:" field as well as +disable honoring any "Mail-Followup-To:" fields in any emails you reply to. +Some email clients come with both enabled by default. Mutt is like this (see +Disable Mail-Followup-To in the Mutt section below). + +[[enable-plain-text-mode]] +== Enable Plain Text Mode + +Most email clients automatically reject mailing list email if it is not a +text/plain formatted email. For that reason, it is important that your email +client is set to create text/plain emails instead of text/enriched or +text/html email. + +[[patches-that-receive-no-response]] + +From Junio's notes from the maintainer: + +> If you sent a patch and you did not hear any response from anybody for +> several days, it could be that your patch was totally uninteresting, +> but it also is possible that it was simply lost in the noise. Please +> do not hesitate to send a reminder message in such a case. Messages +> getting lost in the noise may be a sign that those who can evaluate +> your patch don't have enough mental/time bandwidth to process them +> right at the moment, and it often helps to wait until the list traffic +> becomes calmer before sending such a reminder. + +[[send-merge-ready-patches-to-the-maintainer]] +== Send Merge-Ready Patches to the Maintainer + +Once a patch has achieved consensus and all stakeholders are staisfied and +everything is ready for merging, then you send it to the maintainer: "To: +gitster@pobox.com". + +[[mutt-config]] +== Mutt Config + +This section has suggestions for how to set up Mutt to be polite. + +[[known-mailing-lists]] +=== Known Mailing Lists + +Mutt has the ability to change its behavior when replying to a mailing list. For +Mutt to know when an address is a mailing list, use the `subscribe` keyword in +your Mutt configuration: + +**~/.muttrc:** +``` +# tell Mutt about the Git mailing list +subscribe git@vger.kernel.org +``` + +[[reply-properly]] +=== Reply Properly + +By default, Mutt uses the 'g' and 'L' hotkeys to execute a "group reply" or +"list reply" respectively. A "group reply" creates an email addressed to the +sender with all other recipients in the "Cc". A "list reply" starts an email +addressed only to the mailing list without anybody else as "Cc". + +Per rule X, Y, and Z above, using "group reply" in Mutt is what you want to do. + +[[disable-mail-followup-to]] +=== Disable Mail-Followup-To + +By default, when replying to mailing lists, Mutt will automatically generate +"Mail-Followup-To" headers. To fix this, disable the generation of the header +in your Mutt configuration. It is also a good idea to disable honoring any +"Mail-Followup-To" headers so that any "group reply" operations are correctly +addressed. + +**~/.muttrc:** +``` +# disable Mail-Followup-To header +unset followup_to + +# disable honoring Mail-Followup-To header +unset honor_followup_to +``` +
After violating a few unspoken etiquette rules that were spotted by Christian Couder <christian.couder@gmail.com>, Filipe Contreras <felipe.contreras@gmail.com> suggested that somebody write a guide. Since I was the latest cause of this perenial discussion, I took it upon myself to learn from my mistakes and document the fixes. Thanks to Junio <gitster@pobox.com> for providing links to similar discussions in the past and Stefan Moch <stefanmoc@gmail.com> for pointing out where the related documentation already existed in the tree. Signed-off-by: Dave Huseby <dwh@linuxprogrammer.org> --- Documentation/MailingListEtiquette.txt | 125 +++++++++++++++++++++++++ 1 file changed, 125 insertions(+) create mode 100644 Documentation/MailingListEtiquette.txt