git@vger.kernel.org mailing list mirror (one of many)
 help / color / mirror / code / Atom feed
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


  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).