git.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: Bagas Sanjaya <bagasdotme@gmail.com>
To: Dave Huseby <dwh@linuxprogrammer.org>, git@vger.kernel.org
Cc: christian.couder@gmail.com, felipe.contreras@gmail.com,
	gitster@pobox.com, stefanmoch@mail.de
Subject: Re: [PATCH v2] Writing down mail list etiquette.
Date: Wed, 12 May 2021 11:07:55 +0700	[thread overview]
Message-ID: <80e0215a-cd00-57f9-afb6-b85b33dba91d@gmail.com> (raw)
In-Reply-To: <20210512031821.6498-2-dwh@linuxprogrammer.org>

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.

-- 
An old man doll... just what I always wanted! - Clara

  reply	other threads:[~2021-05-12  4:08 UTC|newest]

Thread overview: 25+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-05-12  2:54 [PATCH v1] " 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 [this message]
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     ` [PATCH v3] doc: writing down Git mailing " Dave Huseby
2021-05-13  0:20       ` 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

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=80e0215a-cd00-57f9-afb6-b85b33dba91d@gmail.com \
    --to=bagasdotme@gmail.com \
    --cc=christian.couder@gmail.com \
    --cc=dwh@linuxprogrammer.org \
    --cc=felipe.contreras@gmail.com \
    --cc=git@vger.kernel.org \
    --cc=gitster@pobox.com \
    --cc=stefanmoch@mail.de \
    --subject='Re: [PATCH v2] Writing down mail list etiquette.' \
    /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

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 NNTP newsgroup(s).