Re: [PATCH v2] Writing down mail list etiquette.

[Junio C Hamano <gitster@pobox.com>]

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.