| Message ID | 20210512233412.10737-1-dwh@linuxprogrammer.org (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | [v3] doc: writing down Git mailing list etiquette | expand |
Dave Huseby <dwh@linuxprogrammer.org> writes: > Documentation/MailingListEtiquette.txt | 93 ++++++++++++++++++++++++++ > Documentation/SubmittingPatches | 74 +++++++++++++++++++- > 2 files changed, 166 insertions(+), 1 deletion(-) > create mode 100644 Documentation/MailingListEtiquette.txt I've read this version over, and did not find much that is objectionable, but as some others said on the previous round, there may be overlaps and repetitions we'd rather get rid of. We should be able to cover discussions around patches in the SubmittingPatches document without introducing a new document, so all that remains is what to do with non-patch discussions. I suspect that it might even be sufficient to (1) taylor descriptions introduced in this patch for discussions around patches and reviews, and add it as a new section to SubmittingPatches and (2) mention that the same principle applies to non-patch communication in the same section as a sidenote but obviously others may disagree. Ævar, you also have some updates to SubmittingPatches in flight. Can I ask you to work with Dave to figure out how well this update fits in the entire picture as a stakeholder to the document (i.e. not as "the guilty party who is involved in conflicts", but as "somebody who has been long enough to be qualified to guide the evolution of the document, and obviously is interested in improving the document")? Thanks. > diff --git a/Documentation/MailingListEtiquette.txt b/Documentation/MailingListEtiquette.txt > new file mode 100644 > index 0000000000..8a383f81a8 > --- /dev/null > +++ b/Documentation/MailingListEtiquette.txt > @@ -0,0 +1,93 @@ > +Mailing List Etiquette > +====================== > + > +[[introduction]] > +== Introduction > + > +The Git project uses a mailing list and email to coordinate development and > +submit patches. Many other open source projects use web-based forums and pull > +requests (PRs) to achieve the same thing. This article focuses entirely on the > +Git project and the etiquette and unspoken rules that have developed over the > +years. What follows are best practices and suggestions for the "proper" way to > +interact via email on the Git mailing list. > + > +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 > + > +The "To:" field is the place to list the people you want to directly interact > +with and request responses from and the "Cc:" field is for other people that > +you wish to inform of this conversation. Everybody is welcome to chime in on > +the thread. When there is no particular person you wish to talk to, the mailing > +list address is a good catch-all addres to reach everybody and should be put in > +the "To:" 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 motivation for the above suggestions is to allow 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. > + > +[[proper-use-of-subject]] > +== Proper Use of the Subject > + > +When replying to an email on the list, make sure that the subject of the > +original email is the subject of your email with "Re:" added to it. So if > +you reply to an email with subject "first post", the subject of your email > +should be "Re: first post". > + > +Sometimes email threads diverge into other threads about related, but distinct > +topics. In those cases, the subject like should change to the new topic and > +include in parenthesis "(Was: <original thread subject>)". So for instance, > +if a side thread is created from the "first post" thread example, the subject > +line should be something like "second post (was: first post)" with replies > +having the subject "Re: second post (was: first post)". > + > +[[use-interleaved-style]] > +== Use Interleaved Style in Replies > + > +> 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 email? > + > +When replying to emails, use interleaved style which is also sometimes called > +an "inline reply". This creates a natural flow for the reader of the reply. They > +can easily see what the context for the reply is. Also leave only the context > +that is important for your reply and delete the rest. > + > +[[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 containing 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"/"group reply" will redirect the > +response to all of the people in the original "Cc:" field instead of going to > +the person who sent the message being responded to. > + > +Some email clients, such as Mutt (see Disable Mail-Followup-To in the Mutt > +section below) are configured by default to add "Mail-Followup-To:" fields and > +to honor existing "Mail-Followup-To:" fields. It is best to disable both. > + > +[[enable-plain-text-mode]] > +== Enable Plain Text Mode > + > +The Git mailing list software rejects email sent in text/html format. It is > +important that your email client is set to create text/plain emails to ensure > +delivery. > diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches > index 55287d72e0..4f8b9f24ee 100644 > --- a/Documentation/SubmittingPatches > +++ b/Documentation/SubmittingPatches > @@ -433,7 +433,7 @@ help you find out who they are. > > In any time between the (2)-(3) cycle, the maintainer may pick it up > from the list and queue it to `seen`, in order to make it easier for > -people play with it without having to pick up and apply the patch to > +people to play with it without having to pick up and apply the patch to > their trees themselves. > > [[patch-status]] > @@ -450,6 +450,46 @@ their trees themselves. > entitled "What's cooking in git.git" and "What's in git.git" giving > the status of various proposed changes. > > +[[patches-that-receive-no-response]] > +== Patches that Receive No Response > + > +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. > + > +Alternatives to sending direct reminders are: > + > +* Wait for the next "What's cooking in git.git" email to see if your patch > + series was mentioned and replying to that email with a note pointing out that > + your patch series has been overlooked. > + > +* Attend the weekly "stand-up" meeting held in the "#git-devel" channel on > + irc.freenode.net and bring it up then. > + > +[[send-merge-ready-patches-to-the-maintainer]] > +== Send Merge-Ready Patches to the Maintainer > + > +Once a patch has achieved consensus and all stakeholders are satisfied and > +everything is ready for merging, you have two main options for getting your > +patch noticed by the maintainer. > + > +1. Submit a new, final, version of the patch with an accurate list of commit > + trailers. Make this submission "To:" the maintainer, "In-Reply-To:" the > + previous version of the patch, and add everybody concerned, including the > + mailing list address to the "Cc:" field. This is a nice way to reduce the > + amount of work the maintainer must do to merge the patch while also getting > + their attention. > + > +2. Creating a "group reply"/"Reply to all" email to the latest patch series > + with the maintainer in the "To:" field. This is sometimes referred to as a > + "review ping" email and is appropriate if the patch requires no more work > + and is in its final state with an accurate list of commit trailers. > + > [[travis]] > == GitHub-Travis CI hints > > @@ -510,6 +550,38 @@ first patch.\n", if you really want to put in the patch e-mail, > should come after the three-dash line that signals the end of the > commit message. > > +=== Mutt > + > +[[known-mailing-lists]] > +==== Known Mailing Lists > + > +Mutt has the ability to change its behavior when replying to a mailing list. You > +must specify mailing list addresses using the `subscribe` keyword in your Mutt > +configuration: > + > +**~/.muttrc:** > +``` > +# tell Mutt about the Git mailing list > +subscribe git@vger.kernel.org > +``` > + > +[[disable-mail-followup-to]] > +==== Disable Mail-Followup-To > + > +By default, when replying to mailing lists, Mutt automatically generates > +"Mail-Followup-To:" fields. To fix this, disable the generation of the field > +in your Mutt configuration. It is also a good idea to disable honoring any > +"Mail-Followup-To:" field so that your "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 > +``` > > === Pine
On 13/05/21 06.34, Dave Huseby wrote: > After violating a few unspoken etiquette rules while submitting patches > to the Git mailing list, it was suggeted 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 Git mailing list > etiquette and the fixes I made to my email setup. > The commit message looks too personal here. Anyways, better say: ``` Developers who are new to Git mailing list may not feel that they violated unspoken etiquette rules in the list until someone point out the discussions about such rules. To avoid such perennial discussions, document the etiquette rules applied to Git mailing list. Also add sections about submitting final (merge-ready) patch, actions when a patch receives no response, and hints for Mutt to Documentation/SubmittingPatches. ``` But anyway for SubmittingPatches changes, I think it's better to send it as separate patch. > * Add documentation specifically on Git mailing list etiquette > * Add alternative actions for patches that receive no response. > * Add section on submitting a final, merge-ready patch. > * Add section on Mutt MUA settings. > > Reported-by: Christian Couder <christian.couder@gmail.com> > Reported-by: Filipe Contreras <felipe.contreras@gmail.com> > Thanks-to: Junio C Hamano <gitster@pobox.com> > Thanks-to: Philip Oakley <philipoakley@iee.email> > Thanks-to: Bagas Sanjaya <bagasdotme@gmail.com> > Thanks-to: Eric Sunshine <sunshine@sunshineco.com> > Thanks-to: Ævar Arnfjörð Bjarmason <avarab@gmail.com> > Signed-off-by: Dave Huseby <dwh@linuxprogrammer.org> > --- > Documentation/MailingListEtiquette.txt | 93 ++++++++++++++++++++++++++ > Documentation/SubmittingPatches | 74 +++++++++++++++++++- > 2 files changed, 166 insertions(+), 1 deletion(-) > create mode 100644 Documentation/MailingListEtiquette.txt > > diff --git a/Documentation/MailingListEtiquette.txt b/Documentation/MailingListEtiquette.txt > new file mode 100644 > index 0000000000..8a383f81a8 > --- /dev/null > +++ b/Documentation/MailingListEtiquette.txt > @@ -0,0 +1,93 @@ > +Mailing List Etiquette > +====================== > + > +[[introduction]] > +== Introduction > + > +The Git project uses a mailing list and email to coordinate development and > +submit patches. Many other open source projects use web-based forums and pull > +requests (PRs) to achieve the same thing. This article focuses entirely on the > +Git project and the etiquette and unspoken rules that have developed over the > +years. What follows are best practices and suggestions for the "proper" way to > +interact via email on the Git mailing list. > + > +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 > + > +The "To:" field is the place to list the people you want to directly interact > +with and request responses from and the "Cc:" field is for other people that > +you wish to inform of this conversation. Everybody is welcome to chime in on > +the thread. When there is no particular person you wish to talk to, the mailing > +list address is a good catch-all addres to reach everybody and should be put in > +the "To:" 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 motivation for the above suggestions is to allow 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. > + > +[[proper-use-of-subject]] > +== Proper Use of the Subject > + > +When replying to an email on the list, make sure that the subject of the > +original email is the subject of your email with "Re:" added to it. So if > +you reply to an email with subject "first post", the subject of your email > +should be "Re: first post". > + > +Sometimes email threads diverge into other threads about related, but distinct > +topics. In those cases, the subject like should change to the new topic and > +include in parenthesis "(Was: <original thread subject>)". So for instance, > +if a side thread is created from the "first post" thread example, the subject > +line should be something like "second post (was: first post)" with replies > +having the subject "Re: second post (was: first post)". > + > +[[use-interleaved-style]] > +== Use Interleaved Style in Replies > + > +> 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 email? > + When you describe about interleaved style below, you also include example of "top posting". This make newbies think that TP (like above) is interleaved style, while both are actually different. So please also include example of interleaved style. > +When replying to emails, use interleaved style which is also sometimes called > +an "inline reply". This creates a natural flow for the reader of the reply. They > +can easily see what the context for the reply is. Also leave only the context > +that is important for your reply and delete the rest. > + > +[[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 containing 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"/"group reply" will redirect the > +response to all of the people in the original "Cc:" field instead of going to > +the person who sent the message being responded to. > + > +Some email clients, such as Mutt (see Disable Mail-Followup-To in the Mutt > +section below) are configured by default to add "Mail-Followup-To:" fields and > +to honor existing "Mail-Followup-To:" fields. It is best to disable both. > + The specific hints for Mutt is on Documentation/SubmittingPatches, included as part of this patch, not on Documentation/MailingListEtiquette.txt that you wrote. > +[[enable-plain-text-mode]] > +== Enable Plain Text Mode > + > +The Git mailing list software rejects email sent in text/html format. It is > +important that your email client is set to create text/plain emails to ensure > +delivery. Don't you know that VGER (that hosts Git ML) rejects text/html emails because these are very likely spam messages? > +[[send-merge-ready-patches-to-the-maintainer]] > +== Send Merge-Ready Patches to the Maintainer > + > +Once a patch has achieved consensus and all stakeholders are satisfied and > +everything is ready for merging, you have two main options for getting your > +patch noticed by the maintainer. > + > +1. Submit a new, final, version of the patch with an accurate list of commit > + trailers. Make this submission "To:" the maintainer, "In-Reply-To:" the > + previous version of the patch, and add everybody concerned, including the > + mailing list address to the "Cc:" field. This is a nice way to reduce the > + amount of work the maintainer must do to merge the patch while also getting > + their attention. > + > +2. Creating a "group reply"/"Reply to all" email to the latest patch series > + with the maintainer in the "To:" field. This is sometimes referred to as a > + "review ping" email and is appropriate if the patch requires no more work > + and is in its final state with an accurate list of commit trailers. > + For this section, I expect that the paragraph that started with "After the list reached a consensus that it is a good idea to apply the patch, re-send it with "To:"..." be also deleted to avoid redundancy. > [[travis]] > == GitHub-Travis CI hints > > @@ -510,6 +550,38 @@ first patch.\n", if you really want to put in the patch e-mail, > should come after the three-dash line that signals the end of the > commit message. > > +=== Mutt > + > +[[known-mailing-lists]] > +==== Known Mailing Lists > + > +Mutt has the ability to change its behavior when replying to a mailing list. You > +must specify mailing list addresses using the `subscribe` keyword in your Mutt > +configuration: > + > +**~/.muttrc:** > +``` > +# tell Mutt about the Git mailing list > +subscribe git@vger.kernel.org > +``` > + > +[[disable-mail-followup-to]] > +==== Disable Mail-Followup-To > + > +By default, when replying to mailing lists, Mutt automatically generates > +"Mail-Followup-To:" fields. To fix this, disable the generation of the field > +in your Mutt configuration. It is also a good idea to disable honoring any > +"Mail-Followup-To:" field so that your "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 > +``` > > === Pine > > From the context hunk for this Mutt subsection, I was thought that it was inside "Travis hints" sub/section, but after seeing "Pine" subsection below the addition, I recognized that subsection for Mutt was in "MUA specific" section. Thanks.
Dave Huseby wrote: > +[[proper-use-of-to-and-cc]] > +== Proper Use of To and Cc Always make sure the mailing list is included. ... > +[[proper-use-of-subject]] > +== Proper Use of the Subject ... I think this is more importan than the point above. > +[[use-interleaved-style]] > +== Use Interleaved Style in Replies > + > +> 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 email? You need to explain this is top-posting, and it's an example of what not to do. ... > +[[do-not-use-mail-followup-to]] > +== Do Not Use Mail-Followup-To ... This should be the last point. > +[[enable-plain-text-mode]] > +== Enable Plain Text Mode > + > +The Git mailing list software rejects email sent in text/html format. It is > +important that your email client is set to create text/plain emails to ensure > +delivery. This is more important than other points. IMO the order should be: 1. Enable plain-text mode 2. Proper use of subject 3. Use interleaved-style 4. Proper use of To/Cc 5. Do not use mail-followup-to > --- a/Documentation/SubmittingPatches > +++ b/Documentation/SubmittingPatches > @@ -433,7 +433,7 @@ help you find out who they are. ... > +[[patches-that-receive-no-response]] > +== Patches that Receive No Response I would put this in a separate patch. Cheers.
Another review. On 13/05/21 06.34, Dave Huseby wrote: > After violating a few unspoken etiquette rules while submitting patches > to the Git mailing list, it was suggeted 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 Git mailing list > etiquette and the fixes I made to my email setup. > > * Add documentation specifically on Git mailing list etiquette > * Add alternative actions for patches that receive no response. > * Add section on submitting a final, merge-ready patch. > * Add section on Mutt MUA settings. > > Reported-by: Christian Couder <christian.couder@gmail.com> > Reported-by: Filipe Contreras <felipe.contreras@gmail.com> > Thanks-to: Junio C Hamano <gitster@pobox.com> > Thanks-to: Philip Oakley <philipoakley@iee.email> > Thanks-to: Bagas Sanjaya <bagasdotme@gmail.com> > Thanks-to: Eric Sunshine <sunshine@sunshineco.com> > Thanks-to: Ævar Arnfjörð Bjarmason <avarab@gmail.com> > Signed-off-by: Dave Huseby <dwh@linuxprogrammer.org> > --- > Documentation/MailingListEtiquette.txt | 93 ++++++++++++++++++++++++++ > Documentation/SubmittingPatches | 74 +++++++++++++++++++- > 2 files changed, 166 insertions(+), 1 deletion(-) > create mode 100644 Documentation/MailingListEtiquette.txt > > diff --git a/Documentation/MailingListEtiquette.txt b/Documentation/MailingListEtiquette.txt > new file mode 100644 > index 0000000000..8a383f81a8 > --- /dev/null > +++ b/Documentation/MailingListEtiquette.txt > @@ -0,0 +1,93 @@ > +Mailing List Etiquette > +====================== > + > +[[introduction]] > +== Introduction > + > +The Git project uses a mailing list and email to coordinate development and > +submit patches. Many other open source projects use web-based forums and pull > +requests (PRs) to achieve the same thing. This article focuses entirely on the > +Git project and the etiquette and unspoken rules that have developed over the > +years. What follows are best practices and suggestions for the "proper" way to > +interact via email on the Git mailing list. > + > +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 > + > +The "To:" field is the place to list the people you want to directly interact > +with and request responses from and the "Cc:" field is for other people that > +you wish to inform of this conversation. Everybody is welcome to chime in on > +the thread. When there is no particular person you wish to talk to, the mailing > +list address is a good catch-all addres to reach everybody and should be put in > +the "To:" 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 motivation for the above suggestions is to allow 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. > + > +[[proper-use-of-subject]] > +== Proper Use of the Subject > + > +When replying to an email on the list, make sure that the subject of the > +original email is the subject of your email with "Re:" added to it. So if > +you reply to an email with subject "first post", the subject of your email > +should be "Re: first post". > + > +Sometimes email threads diverge into other threads about related, but distinct > +topics. In those cases, the subject like should change to the new topic and > +include in parenthesis "(Was: <original thread subject>)". So for instance, > +if a side thread is created from the "first post" thread example, the subject > +line should be something like "second post (was: first post)" with replies > +having the subject "Re: second post (was: first post)". > + > +[[use-interleaved-style]] > +== Use Interleaved Style in Replies > + > +> 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 email? > + > +When replying to emails, use interleaved style which is also sometimes called > +an "inline reply". This creates a natural flow for the reader of the reply. They > +can easily see what the context for the reply is. Also leave only the context > +that is important for your reply and delete the rest. > + > +[[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 containing 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"/"group reply" will redirect the > +response to all of the people in the original "Cc:" field instead of going to > +the person who sent the message being responded to. > + > +Some email clients, such as Mutt (see Disable Mail-Followup-To in the Mutt > +section below) are configured by default to add "Mail-Followup-To:" fields and > +to honor existing "Mail-Followup-To:" fields. It is best to disable both. > + > +[[enable-plain-text-mode]] > +== Enable Plain Text Mode > + > +The Git mailing list software rejects email sent in text/html format. It is > +important that your email client is set to create text/plain emails to ensure > +delivery. > diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches > index 55287d72e0..4f8b9f24ee 100644 > --- a/Documentation/SubmittingPatches > +++ b/Documentation/SubmittingPatches > @@ -433,7 +433,7 @@ help you find out who they are. > > In any time between the (2)-(3) cycle, the maintainer may pick it up > from the list and queue it to `seen`, in order to make it easier for > -people play with it without having to pick up and apply the patch to > +people to play with it without having to pick up and apply the patch to > their trees themselves. > > [[patch-status]] > @@ -450,6 +450,46 @@ their trees themselves. > entitled "What's cooking in git.git" and "What's in git.git" giving > the status of various proposed changes. > > +[[patches-that-receive-no-response]] > +== Patches that Receive No Response > + > +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. > + > +Alternatives to sending direct reminders are: > + > +* Wait for the next "What's cooking in git.git" email to see if your patch > + series was mentioned and replying to that email with a note pointing out that > + your patch series has been overlooked. > + > +* Attend the weekly "stand-up" meeting held in the "#git-devel" channel on > + irc.freenode.net and bring it up then. > + > +[[send-merge-ready-patches-to-the-maintainer]] > +== Send Merge-Ready Patches to the Maintainer > + > +Once a patch has achieved consensus and all stakeholders are satisfied and > +everything is ready for merging, you have two main options for getting your > +patch noticed by the maintainer. > + > +1. Submit a new, final, version of the patch with an accurate list of commit > + trailers. Make this submission "To:" the maintainer, "In-Reply-To:" the > + previous version of the patch, and add everybody concerned, including the > + mailing list address to the "Cc:" field. This is a nice way to reduce the > + amount of work the maintainer must do to merge the patch while also getting > + their attention. > + > +2. Creating a "group reply"/"Reply to all" email to the latest patch series > + with the maintainer in the "To:" field. This is sometimes referred to as a > + "review ping" email and is appropriate if the patch requires no more work > + and is in its final state with an accurate list of commit trailers. > + > [[travis]] > == GitHub-Travis CI hints > > @@ -510,6 +550,38 @@ first patch.\n", if you really want to put in the patch e-mail, > should come after the three-dash line that signals the end of the > commit message. > > +=== Mutt > + > +[[known-mailing-lists]] > +==== Known Mailing Lists > + > +Mutt has the ability to change its behavior when replying to a mailing list. You > +must specify mailing list addresses using the `subscribe` keyword in your Mutt > +configuration: > + > +**~/.muttrc:** > +``` > +# tell Mutt about the Git mailing list > +subscribe git@vger.kernel.org > +``` > + > +[[disable-mail-followup-to]] > +==== Disable Mail-Followup-To > + > +By default, when replying to mailing lists, Mutt automatically generates > +"Mail-Followup-To:" fields. To fix this, disable the generation of the field > +in your Mutt configuration. It is also a good idea to disable honoring any > +"Mail-Followup-To:" field so that your "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 > +``` > > === Pine > > I think the patch title, according to diff body, should be "doc: document mailing list etiquette and various updates to SubmittingPatches". But anyway, it's better to split into two separate patches (one that document etiquette and one that add updates to SubmittingPatches) because there are two logical changes in single patch. Regarding patch title, I proposed change above because we require that the title use imperative language ("make something do one thing"). However, you use present continuous tense (with gerund "-ing"), which implied that you do something progressively ("making something do one thing"). This is not imperative language, just descriptive.
On 13.05.2021 09:20, Junio C Hamano wrote: >I've read this version over, and did not find much that is >objectionable, but as some others said on the previous round, there >may be overlaps and repetitions we'd rather get rid of. We should >be able to cover discussions around patches in the SubmittingPatches >document without introducing a new document, so all that remains is >what to do with non-patch discussions. I suspect that it might even >be sufficient to (1) taylor descriptions introduced in this patch >for discussions around patches and reviews, and add it as a new >section to SubmittingPatches and (2) mention that the same principle >applies to non-patch communication in the same section as a sidenote >but obviously others may disagree. I realized last night that there is an important distinction between using email to work *with* Git and using email to work *on* Git. The Git ML has its own etiquette and rules and MUA tweaks that may not apply to other projects that use Git and a mailing list. The files MyFirstContribution.txt and SubmittingPatches are clearly focused on using email to work *on* Git. The file MyFirstObjectWalk.txt is also about working *on* Git, although unrelated to email and the mailing list. Maybe it's time we make the *on*/*with* distinction more obvious by creating a Documentation/WorkingOnGit subdir? Just throwing that out there. It sounds to me like adding a MailingListEtiquette.txt file isn't the favored approach. I can tailor the information in here to fit into new sections of SubmittingPatches. >Ævar, you also have some updates to SubmittingPatches in flight. > >Can I ask you to work with Dave to figure out how well this update >fits in the entire picture as a stakeholder to the document (i.e. >not as "the guilty party who is involved in conflicts", but as >"somebody who has been long enough to be qualified to guide the >evolution of the document, and obviously is interested in improving >the document")? I saw Ævar's patches last night and had the same thought. Since it looks like this is probably all going into SubmittingPatches, I'll connect with Ævar and see if we can come up with a patch series for (1) Ævar's re-org and pruning (2) my Mutt MUA settings and (3) etiquette related information for discussions around patches and reviews with a (4) side note for any general etiquette for non-patch communication. Thoughts? >Thanks. No, thank you. And thank you to Felipe and Bagas for such thorough reviews.
Dave Huseby wrote: > It sounds to me like adding a MailingListEtiquette.txt file isn't the > favored approach. I can tailor the information in here to fit into new > sections of SubmittingPatches. I don't think this belongs to SubmittingPatches because it applies to *everyone*, yes people submitting patches, but also people reviewing patches. Additionally people submitting bug reports, people responding to bug reports. People suggesting improvements. And of course people maintainging the project too. Also, any other discussions.
Dave Huseby <dwh@linuxprogrammer.org> writes: > I realized last night that there is an important distinction between > using email to work *with* Git and using email to work *on* Git. The Git > ML has its own etiquette and rules and MUA tweaks that may not apply to > other projects that use Git and a mailing list. The files > MyFirstContribution.txt and SubmittingPatches are clearly focused on > using email to work *on* Git. The file MyFirstObjectWalk.txt is also > about working *on* Git, although unrelated to email and the mailing > list. Maybe it's time we make the *on*/*with* distinction more obvious > by creating a Documentation/WorkingOnGit subdir? Just throwing that out > there. I agree with that "realization", and think we shouldn't talk anything about what other people who happens to use Git for their projects should do, at least for now, when we do not even have a completed written guideline for ourselves to follow when using Git for our projects. > I saw Ævar's patches last night and had the same thought. Since it looks > like this is probably all going into SubmittingPatches, I'll connect > with Ævar and see if we can come up with a patch series for (1) Ævar's > re-org and pruning (2) my Mutt MUA settings and (3) etiquette related > information for discussions around patches and reviews with a (4) side > note for any general etiquette for non-patch communication. Sounds good. Thanks.
Dave Huseby wrote: > After violating a few unspoken etiquette rules while submitting patches > to the Git mailing list, it was suggeted 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 Git mailing list > etiquette and the fixes I made to my email setup. > > * Add documentation specifically on Git mailing list etiquette > * Add alternative actions for patches that receive no response. > * Add section on submitting a final, merge-ready patch. > * Add section on Mutt MUA settings. > > Reported-by: Christian Couder <christian.couder@gmail.com> > Reported-by: Filipe Contreras <felipe.contreras@gmail.com> > Thanks-to: Junio C Hamano <gitster@pobox.com> > Thanks-to: Philip Oakley <philipoakley@iee.email> > Thanks-to: Bagas Sanjaya <bagasdotme@gmail.com> > Thanks-to: Eric Sunshine <sunshine@sunshineco.com> > Thanks-to: Ævar Arnfjörð Bjarmason <avarab@gmail.com> > Signed-off-by: Dave Huseby <dwh@linuxprogrammer.org> What happened to this? I see value in having this document, so I would be glad to pick it up if you've lost interest. Cheers.
On 09.06.2021 12:36, Felipe Contreras wrote: >What happened to this? I see value in having this document, so I would >be glad to pick it up if you've lost interest. I fell off of the face of the earth. My life turned upside down but it's slowly righting itself. A number of things took me offline but the last of which is my father nearing the end of his life. Things are stable for the moment so I am getting back in the saddle. Like I said in my last update, I'm going to try to combine all of the contributions and feedback into a patchset that includes Ævar's patches and cleaned up versions of mine on top. Right now I'm trying to get my head back where it was. Cheers! Dave
Dave Huseby wrote: > On 09.06.2021 12:36, Felipe Contreras wrote: > >What happened to this? I see value in having this document, so I would > >be glad to pick it up if you've lost interest. > > I fell off of the face of the earth. My life turned upside down but it's > slowly righting itself. A number of things took me offline but the last > of which is my father nearing the end of his life. Things are stable for > the moment so I am getting back in the saddle. Like I said in my last > update, I'm going to try to combine all of the contributions and > feedback into a patchset that includes Ævar's patches and cleaned up > versions of mine on top. > > Right now I'm trying to get my head back where it was. Sorry to hear that. Hopefully soon you'll find some familiar ground. Cheers.
diff --git a/Documentation/MailingListEtiquette.txt b/Documentation/MailingListEtiquette.txt new file mode 100644 index 0000000000..8a383f81a8 --- /dev/null +++ b/Documentation/MailingListEtiquette.txt @@ -0,0 +1,93 @@ +Mailing List Etiquette +====================== + +[[introduction]] +== Introduction + +The Git project uses a mailing list and email to coordinate development and +submit patches. Many other open source projects use web-based forums and pull +requests (PRs) to achieve the same thing. This article focuses entirely on the +Git project and the etiquette and unspoken rules that have developed over the +years. What follows are best practices and suggestions for the "proper" way to +interact via email on the Git mailing list. + +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 + +The "To:" field is the place to list the people you want to directly interact +with and request responses from and the "Cc:" field is for other people that +you wish to inform of this conversation. Everybody is welcome to chime in on +the thread. When there is no particular person you wish to talk to, the mailing +list address is a good catch-all addres to reach everybody and should be put in +the "To:" 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 motivation for the above suggestions is to allow 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. + +[[proper-use-of-subject]] +== Proper Use of the Subject + +When replying to an email on the list, make sure that the subject of the +original email is the subject of your email with "Re:" added to it. So if +you reply to an email with subject "first post", the subject of your email +should be "Re: first post". + +Sometimes email threads diverge into other threads about related, but distinct +topics. In those cases, the subject like should change to the new topic and +include in parenthesis "(Was: <original thread subject>)". So for instance, +if a side thread is created from the "first post" thread example, the subject +line should be something like "second post (was: first post)" with replies +having the subject "Re: second post (was: first post)". + +[[use-interleaved-style]] +== Use Interleaved Style in Replies + +> 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 email? + +When replying to emails, use interleaved style which is also sometimes called +an "inline reply". This creates a natural flow for the reader of the reply. They +can easily see what the context for the reply is. Also leave only the context +that is important for your reply and delete the rest. + +[[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 containing 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"/"group reply" will redirect the +response to all of the people in the original "Cc:" field instead of going to +the person who sent the message being responded to. + +Some email clients, such as Mutt (see Disable Mail-Followup-To in the Mutt +section below) are configured by default to add "Mail-Followup-To:" fields and +to honor existing "Mail-Followup-To:" fields. It is best to disable both. + +[[enable-plain-text-mode]] +== Enable Plain Text Mode + +The Git mailing list software rejects email sent in text/html format. It is +important that your email client is set to create text/plain emails to ensure +delivery. diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 55287d72e0..4f8b9f24ee 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -433,7 +433,7 @@ help you find out who they are. In any time between the (2)-(3) cycle, the maintainer may pick it up from the list and queue it to `seen`, in order to make it easier for -people play with it without having to pick up and apply the patch to +people to play with it without having to pick up and apply the patch to their trees themselves. [[patch-status]] @@ -450,6 +450,46 @@ their trees themselves. entitled "What's cooking in git.git" and "What's in git.git" giving the status of various proposed changes. +[[patches-that-receive-no-response]] +== Patches that Receive No Response + +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. + +Alternatives to sending direct reminders are: + +* Wait for the next "What's cooking in git.git" email to see if your patch + series was mentioned and replying to that email with a note pointing out that + your patch series has been overlooked. + +* Attend the weekly "stand-up" meeting held in the "#git-devel" channel on + irc.freenode.net and bring it up then. + +[[send-merge-ready-patches-to-the-maintainer]] +== Send Merge-Ready Patches to the Maintainer + +Once a patch has achieved consensus and all stakeholders are satisfied and +everything is ready for merging, you have two main options for getting your +patch noticed by the maintainer. + +1. Submit a new, final, version of the patch with an accurate list of commit + trailers. Make this submission "To:" the maintainer, "In-Reply-To:" the + previous version of the patch, and add everybody concerned, including the + mailing list address to the "Cc:" field. This is a nice way to reduce the + amount of work the maintainer must do to merge the patch while also getting + their attention. + +2. Creating a "group reply"/"Reply to all" email to the latest patch series + with the maintainer in the "To:" field. This is sometimes referred to as a + "review ping" email and is appropriate if the patch requires no more work + and is in its final state with an accurate list of commit trailers. + [[travis]] == GitHub-Travis CI hints @@ -510,6 +550,38 @@ first patch.\n", if you really want to put in the patch e-mail, should come after the three-dash line that signals the end of the commit message. +=== Mutt + +[[known-mailing-lists]] +==== Known Mailing Lists + +Mutt has the ability to change its behavior when replying to a mailing list. You +must specify mailing list addresses using the `subscribe` keyword in your Mutt +configuration: + +**~/.muttrc:** +``` +# tell Mutt about the Git mailing list +subscribe git@vger.kernel.org +``` + +[[disable-mail-followup-to]] +==== Disable Mail-Followup-To + +By default, when replying to mailing lists, Mutt automatically generates +"Mail-Followup-To:" fields. To fix this, disable the generation of the field +in your Mutt configuration. It is also a good idea to disable honoring any +"Mail-Followup-To:" field so that your "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 +``` === Pine
After violating a few unspoken etiquette rules while submitting patches to the Git mailing list, it was suggeted 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 Git mailing list etiquette and the fixes I made to my email setup. * Add documentation specifically on Git mailing list etiquette * Add alternative actions for patches that receive no response. * Add section on submitting a final, merge-ready patch. * Add section on Mutt MUA settings. Reported-by: Christian Couder <christian.couder@gmail.com> Reported-by: Filipe Contreras <felipe.contreras@gmail.com> Thanks-to: Junio C Hamano <gitster@pobox.com> Thanks-to: Philip Oakley <philipoakley@iee.email> Thanks-to: Bagas Sanjaya <bagasdotme@gmail.com> Thanks-to: Eric Sunshine <sunshine@sunshineco.com> Thanks-to: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Dave Huseby <dwh@linuxprogrammer.org> --- Documentation/MailingListEtiquette.txt | 93 ++++++++++++++++++++++++++ Documentation/SubmittingPatches | 74 +++++++++++++++++++- 2 files changed, 166 insertions(+), 1 deletion(-) create mode 100644 Documentation/MailingListEtiquette.txt