| Message ID | 20210512031821.6498-2-dwh@linuxprogrammer.org (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | [v2] Writing down mail list etiquette. | expand |
On 12/05/21 10.18, 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. > 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 <stefanmoch@mail.de> 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 > > 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. > + But not all open source projects use mailing lists. Most (but not all, also excluding Git) projects use Pull Requests (PR) as a way to submit patches and for review. Of course, some projects that use PR also coordinate their development using mailing lists, patches submissions are done the other way. So we can say "Several (but not all) open source, community projects such as Git use a mailing list to coordinate development AND to submit patches for review". Note the emphasized AND. > +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). > + Better say "Some email clients, such as Mutt (see Disable Mail-Followup-To in mutt-config section below) come with both enabled by default." > +[[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. > + Is "Review ping" enough for reminder purpose? > +[[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". > + I see the typo. s/staisfied/satisfied/ Let's say that we had consented that my patch series was deemed ready at v5 version. From the paragraph above, I interpreted it as "now my series was consented ready, I need to send v6 to Junio (current Git maintainer)". In practice, the maintainer could instead merged v5 (without having me to send v6 [final]), because v5 is merge-ready in absence of maintainer's email address in either To: or Cc:. Oh yeah, should mailing list's address be also in To:/Cc: when sending merge-ready patch series? > +[[mutt-config]] > +== Mutt Config > + > +This section has suggestions for how to set up Mutt to be polite. > + Better say "This section suggests how to set up Mutt to be conformant to the etiquette above.". > +[[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: > + Better say "... specify mailing list address on `subscribe` command 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 > +``` > + > Thanks.
Dave Huseby <dwh@linuxprogrammer.org> writes: > +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. Please ensure that we do *not* sound like dictating our rules on broader open-source community. The document merely talks about the rules followed in _our_ community (iow, git@vger.kernel.org mailing list). > +[[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. The above two say "do X" but lack "because Y". Even when starting a new discussion thread, it is perfectly fine to have specific people on To: while keeping general community members in the loop by CC:ing the list. You'd summon area expert that way. I think the above two items can be viewed from a different angle as a mere consequence of a single guiding principle. "To:" is the place to list the people you want to directly interact with and request responses from, and "Cc:" is for other people, to whom you would want to inform this conversation is going on, but you do not necessarily need to hear their opinion from (they are of course welcome to chime in). And as a consequence of that, the two rules you wrote will fall out naturally. If you have people in mind that you want to directly talk to and/or expect their reaction from, list them on "To"; everybody else goes to "Cc:'. When there is no particular person to talk to, the mailing list address is a good catch-all address to reach everybody, hoping there may be some people who are interested enough to respond. The above is the "do X" part. We need to explain why we want readers to do so, i.e. "because Y". This allows recipients to prioritize their incoming messages; they can direct their immediate attention to those messages with their names on the To: field and the ones with their names on the Cc: field can wait. > +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. This one has both "do X, because Y". Good. > +[[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). ... because "Reply to all" will redirect the response to all the folks that were originally on "cc:", instead of going to the person who sent the message that is being responded to. > 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. Is this true? I know that _our_ mailing list will reject text/html e-mail and that is why we ask people to send text/plain e-mails. I doubt that some/many/most clients reject non text messages. > +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". This needs to be cc'ed to the list. But I am not sure if it needs to be duplicated in this document. Practically nobody seems to do this and expect me to pick things up instead.
Bagas Sanjaya wrote: > Let's say that we had consented that my patch series was deemed ready at > v5 version. From the paragraph above, I interpreted it as "now my series > was consented ready, I need to send v6 to Junio (current Git maintainer)". > In practice, the maintainer could instead merged v5 (without having me to > send v6 [final]), because v5 is merge-ready in absence of maintainer's > email address in either To: or Cc:. Yes and no. Consensus, mearge-ready status, and merged, are three very diffent concepts. Generally they are one-and-the-same, but not always. 1. A patch can have consensus, and yet Junio doesn't merge it 2. A patch may not have consensus, and yet Junio merges it 3. A patch may be merge-ready, no consensus, and yet merged 4. A patch may be merge-ready, no consensus, and unmerged ... I'm not going through every combination... You get the point. Generally you don't need to worry about this, that's Junio's job. If your patch is ready, Junio will merge it... But not always. So no, you don't need to send v6, Junio will pick v5. If he doesn't, it's most likely because it slipped through the cracks, and you can see that in the next "What's cooking in git.git". If you don't see your merge-ready patch series in "what's cooking", then by all means send it again as v6, or reply to the "what's cooking" or something. But generally there's no point in sending a v6 identical to a v5. Just poke Junio. > Oh yeah, should mailing list's address be also in To:/Cc: when sending > merge-ready patch series? IMO the maxim should be: if it's relevant to git, send it to to the git mailing list... *Always*... Don't ever hesitate. But if you already sent a v5 that is is merge-ready, there's no need to send an identical v6. All these suggestions are of course based on my own experience. Others might have different experiences. Cheers.
On Wed, May 12, 2021 at 2:45 AM Felipe Contreras <felipe.contreras@gmail.com> wrote: > Bagas Sanjaya wrote: > > In practice, the maintainer could instead merged v5 (without having me to > > send v6 [final]), because v5 is merge-ready in absence of maintainer's > > email address in either To: or Cc:. > > Generally you don't need to worry about this, that's Junio's job. If > your patch is ready, Junio will merge it... But not always. > > So no, you don't need to send v6, Junio will pick v5. If he doesn't, > it's most likely because it slipped through the cracks, and you can see > that in the next "What's cooking in git.git". > > If you don't see your merge-ready patch series in "what's cooking", then > by all means send it again as v6, or reply to the "what's cooking" or > something. But generally there's no point in sending a v6 identical to a > v5. > > But if you already sent a v5 that is is merge-ready, there's no need > to send an identical v6. > > All these suggestions are of course based on my own experience. Others > might have different experiences. This has been my experience, as well. I've never sent a v6 with Junio as an explicit recipient, but which was otherwise identical to v5. Another reason to avoid sending v6 which is identical to v5 is that it potentially wastes reviewer bandwidth. The advice which seems to have triggered this particular discussion comes from Documentation/SubmittingPatches: After the list reached a consensus that it is a good idea to apply the patch, re-send it with "To:" set to the maintainer{current-maintainer} and "cc:" the list{git-ml} for inclusion. This is especially relevant when the maintainer did not heavily participate in the discussion and instead left the review to trusted others. It's not the first time this advice has resulted in confusion. Perhaps now would a good time to retire it altogether, or at least rewrite it to mention the points you gave above about responding to "What's Cooking" or by sending a "ping" to the original patch email (which may result in Junio either picking up the patch or responding with an explanation as to why he didn't). Following the above SubmittingPatches paragraph is another which also seems to mislead people frequently: Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and `Tested-by:` lines as necessary to credit people who helped your patch, and "cc:" them when sending such a final version for inclusion. In fact, a submitter should almost never add a Reviewed-by: trailer because Reviewed-by: is explicitly given by a reviewer only when the reviewer is satisfied that the patch is merge-ready, in which case no more re-rolls are expected. Instead, these particular trailers are almost always added by Junio based upon reviewer responses he sees when picking up a patch. So, it may be time, too, either to remove this paragraph or to revise it to mention other trailers more appropriate for use by the patch submitter, such as Helped-by:, Suggested-by:, perhaps Co-authored-by:, etc.
Eric Sunshine wrote: > On Wed, May 12, 2021 at 2:45 AM Felipe Contreras > <felipe.contreras@gmail.com> wrote: > > Bagas Sanjaya wrote: > > > In practice, the maintainer could instead merged v5 (without having me to > > > send v6 [final]), because v5 is merge-ready in absence of maintainer's > > > email address in either To: or Cc:. > > > > Generally you don't need to worry about this, that's Junio's job. If > > your patch is ready, Junio will merge it... But not always. > > > > So no, you don't need to send v6, Junio will pick v5. If he doesn't, > > it's most likely because it slipped through the cracks, and you can see > > that in the next "What's cooking in git.git". > > > > If you don't see your merge-ready patch series in "what's cooking", then > > by all means send it again as v6, or reply to the "what's cooking" or > > something. But generally there's no point in sending a v6 identical to a > > v5. > > > > But if you already sent a v5 that is is merge-ready, there's no need > > to send an identical v6. > > > > All these suggestions are of course based on my own experience. Others > > might have different experiences. > > This has been my experience, as well. I've never sent a v6 with Junio > as an explicit recipient, but which was otherwise identical to v5. > > Another reason to avoid sending v6 which is identical to v5 is that it > potentially wastes reviewer bandwidth. > > The advice which seems to have triggered this particular discussion > comes from Documentation/SubmittingPatches: > > After the list reached a consensus that it is a good idea to > apply the patch, re-send it with "To:" set to the > maintainer{current-maintainer} and "cc:" the list{git-ml} for > inclusion. This is especially relevant when the maintainer did > not heavily participate in the discussion and instead left the > review to trusted others. > > It's not the first time this advice has resulted in confusion. Perhaps > now would a good time to retire it altogether, or at least rewrite it > to mention the points you gave above about responding to "What's > Cooking" or by sending a "ping" to the original patch email (which may > result in Junio either picking up the patch or responding with an > explanation as to why he didn't). Agreed. (Although sometimes a patch series of mine has actually received consensus, and yet for some reason Junio does not pick it up. Except in that case sending a v6 certainly would not improve the situation. Not sure if that's specific to me though.) > Following the above SubmittingPatches paragraph is another which also > seems to mislead people frequently: > > Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` > and `Tested-by:` lines as necessary to credit people who helped > your patch, and "cc:" them when sending such a final version for > inclusion. > > In fact, a submitter should almost never add a Reviewed-by: trailer > because Reviewed-by: is explicitly given by a reviewer only when the > reviewer is satisfied that the patch is merge-ready, in which case no > more re-rolls are expected. Instead, these particular trailers are > almost always added by Junio based upon reviewer responses he sees > when picking up a patch. I don't fully agree with that comment. At least me personally if I see people acking v5, I add them to v6 as Reviewed-By. I'm not sure if that makes any difference to Junio, but that's what I've historically done. Cheers.
On Tue, May 11 2021, 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. > 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 <stefanmoch@mail.de> for > pointing out where the related documentation already existed in the > tree. Improvements in this area are most needed, so thanks for working on this. We should not have a new file describing this though, we already cover the content you're adding here partially in Documentation/SubmittingPatches, and some more in Documentation/MyFirstContribution.txt (e.g. a passing mention of in-reply-to etiquette), with this applied we'd have discussion of these related topics in three places. I had some rough WIP patches to update Documentation/SubmittingPatches to address some of what you're adding here, which I've discarded, but I submitted some related patches just now as [1]. As you can see from that topic we e.g. already have MUA-specific tips in Documentation/SubmittingPatches, your addition of a section discussing mutt's config here is another thing we'd be duplicating/unnecessarily splitting across multiple places. I do think it's going to be hard to update SubmittingPatches, for example it has a long section going on about the specific format of patches to craft for the ML, as if anyone's using anything other than git-format-patch these days (it was written before that existed/was as established). I suspect though that any suggestion to simply remove most/all of that for simplicity will probably be met with (IMO unwarranted resistance), which is why I gave up on this the other day before even submitting patches to the ML. But regardless of that, the post-image after your patch of having another place we discuss the same/related topic would be worse, we really should have one canonical guide, so your patch(es) should be amending/splitting Documentation/SubmittingPatches, not duplicating it. 1. https://lore.kernel.org/git/cover-0.3-0000000000-20210512T084137Z-avarab@gmail.com/
Eric Sunshine <sunshine@sunshineco.com> writes: > This has been my experience, as well. I've never sent a v6 with Junio > as an explicit recipient, but which was otherwise identical to v5. It mostly is because I've been too helpful than the written rule to proactively pick up v5, before the participants of the discussion explicitly reaches concensus that it is good enough. In an ideal world, patches in areas that I do not have particular interest in and that other reviewers with good taste are performing good reviews, I should be able to keep myself completely out of the picture, not involved in their review discussion in any way, and not even having to monitor if the discussion reached some concensus, and purely play a patch-monkey for such patches. That, combined with more reviewers with good tastes, would allow us to injest patches at faster rate than we currently can. > Another reason to avoid sending v6 which is identical to v5 is that it > potentially wastes reviewer bandwidth. As long as it is marked as "this is the final version that is identical to the previous round, only difference from which is that the collected reviewed-by and acked-by have been added", it would not waste reviewer bandwidth. The reviewers _should_ however notice if it has questionable changes since the "previous round", in which case their reviewed-by's may now be invalid, of course, though. > The advice which seems to have triggered this particular discussion > comes from Documentation/SubmittingPatches: > > After the list reached a consensus that it is a good idea to > apply the patch, re-send it with "To:" set to the > maintainer{current-maintainer} and "cc:" the list{git-ml} for > inclusion. This is especially relevant when the maintainer did > not heavily participate in the discussion and instead left the > review to trusted others. > > It's not the first time this advice has resulted in confusion. Perhaps > now would a good time to retire it altogether, or at least rewrite it > to mention the points you gave above about responding to "What's > Cooking" or by sending a "ping" to the original patch email (which may > result in Junio either picking up the patch or responding with an > explanation as to why he didn't). No, please do not put _more_ tasks on my plate. The "send the final with everybody's concensus" is an ideal that tries to reduce the maintainer bottleneck by distributing the work of final validation. I've been too helpful in this area in that I have often been the one who does the "ping" ("What is the status of this topic?"), but that would _not_ scale. Anything that the party with more numbers, namely the contributors, can do, we should farm it out to them. > Following the above SubmittingPatches paragraph is another which also > seems to mislead people frequently: > > Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` > and `Tested-by:` lines as necessary to credit people who helped > your patch, and "cc:" them when sending such a final version for > inclusion. > > In fact, a submitter should almost never add a Reviewed-by: trailer > because Reviewed-by: is explicitly given by a reviewer only when the > reviewer is satisfied that the patch is merge-ready, in which case no > more re-rolls are expected. Yes, that is exactly why v6 that is identical to v5 that all reviewers are happy with is useful. It should be able to carry reviewed-by's and acked-by's, reviewers can audit that there is no forged or otherwise inappropriate reviewed-by's, without placing any extra burden on the maintainer. Thanks.
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 <stefanmoch@mail.de> 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