From: Dave Huseby <dwh@linuxprogrammer.org>
To: git@vger.kernel.org
Cc: christian.couder@gmail.com, felipe.contreras@gmail.com,
gitster@pobox.com, stefanmoch@mail.de, philipoak@iee.email,
bagasdotme@gmail.com, sunshine@sunshineco.com, avarab@gmail.com
Subject: [PATCH v3] doc: writing down Git mailing list etiquette
Date: Wed, 12 May 2021 16:34:12 -0700 [thread overview]
Message-ID: <20210512233412.10737-1-dwh@linuxprogrammer.org> (raw)
In-Reply-To: <20210512031821.6498-2-dwh@linuxprogrammer.org>
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
--
2.20.1
next prev parent reply other threads:[~2021-05-12 23:57 UTC|newest]
Thread overview: 25+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-05-12 2:54 [PATCH v1] Writing down mail list etiquette Dave Huseby
2021-05-12 2:57 ` Dave Huseby
2021-05-12 6:25 ` Felipe Contreras
2021-05-12 3:18 ` Dave Huseby
2021-05-12 3:18 ` [PATCH v2] Writing down mail list etiquette Dave Huseby
2021-05-12 4:07 ` Bagas Sanjaya
2021-05-12 6:45 ` Felipe Contreras
2021-05-12 7:35 ` Eric Sunshine
2021-05-12 8:32 ` Felipe Contreras
2021-05-12 14:36 ` Junio C Hamano
2021-05-12 4:46 ` Junio C Hamano
2021-05-12 8:45 ` Ævar Arnfjörð Bjarmason
2021-05-12 23:34 ` Dave Huseby [this message]
2021-05-13 0:20 ` [PATCH v3] doc: writing down Git mailing " Junio C Hamano
2021-05-13 17:17 ` Dave Huseby
2021-05-13 20:04 ` Felipe Contreras
2021-05-13 21:11 ` Junio C Hamano
2021-05-13 4:06 ` Bagas Sanjaya
2021-05-13 6:34 ` Felipe Contreras
2021-05-13 7:01 ` Bagas Sanjaya
2021-06-09 17:36 ` Felipe Contreras
2021-06-18 20:43 ` Dave Huseby
2021-06-18 23:48 ` Felipe Contreras
2021-05-12 15:28 ` and... Re: [PATCH v1] Writing down mail " Philip Oakley
2021-05-12 6:21 ` Felipe Contreras
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20210512233412.10737-1-dwh@linuxprogrammer.org \
--to=dwh@linuxprogrammer.org \
--cc=avarab@gmail.com \
--cc=bagasdotme@gmail.com \
--cc=christian.couder@gmail.com \
--cc=felipe.contreras@gmail.com \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.com \
--cc=philipoak@iee.email \
--cc=stefanmoch@mail.de \
--cc=sunshine@sunshineco.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).