{"thread":{"id":"55667","subject":"[PATCH v1] Writing down mail list etiquette.","startedAt":"2021-05-12T02:54:51Z","lastAt":"2021-06-18T23:48:30Z","messageCount":25,"participants":["Dave Huseby","Bagas Sanjaya","Junio C Hamano","Felipe Contreras","Eric Sunshine","Ævar Arnfjörð Bjarmason","Philip Oakley"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"424260","messageId":"20210512025447.6068-1-dwh@linuxprogrammer.org","threadId":"55667","inReplyTo":null,"subject":"[PATCH v1] Writing down mail list etiquette.","fromName":"Dave Huseby","fromEmail":"dwh@linuxprogrammer.org","sentAt":"2021-05-12T02:54:47Z","receivedAt":"2021-05-12T02:54:51Z","isPatch":true,"sender":{"key":"dwh@linuxprogrammer.org","avatar":null},"body":"After violating a few unspoken etiquette rules that were spotted by\nChristian Couder , Filipe Contreras\n suggested that somebody write a guide.\nSince I was the latest cause of this perenial discussion, I took it upon\nmyself to learn from my mistakes and document the fixes.\n\nThanks to Junio for providing links to similar\ndiscussions in the past and Stefan Moch for\npointing out where the related documentation already existed in the\ntree.\n\nSigned-off-by: Dave Huseby \n---\n Documentation/MailingListEtiquette.txt | 125 +++++++++++++++++++++++++\n 1 file changed, 125 insertions(+)\n create mode 100644 Documentation/MailingListEtiquette.txt\n\ndiff --git a/Documentation/MailingListEtiquette.txt b/Documentation/MailingListEtiquette.txt\nnew file mode 100644\nindex 0000000000..9da2d490aa\n--- /dev/null\n+++ b/Documentation/MailingListEtiquette.txt\n@@ -0,0 +1,125 @@\n+Mailing List Etiquette\n+======================\n+\n+[[introduction]]\n+== Introduction\n+\n+Open source, community projects such as Git use a mailing list and email to\n+coordinate development and to submit patches for review. This article documents\n+the unspoken rules and etiquette for the proper way to send email to the\n+mailing list. What follows are considered best practices to follow.\n+\n+If you are looking for details on how to submit a patch, that is documented\n+elsewhere in:\n+\n+- `Documentation/SubmittingPatches`\n+- `Documentation/MyFirstContribution.txt`\n+\n+[[proper-use-of-to-and-cc]]\n+== Proper Use of To and Cc\n+\n+When starting a new email thread that is not directed at any specific person,\n+put the mailing list address in the \"To:\" field, otherwise address it to the\n+person and put the mailing list address in the \"Cc:\" field.\n+\n+When replying to an email on the mailing list, put the person you are replying\n+to in the \"To:\" field and all other people in the thread in the \"Cc:\" field,\n+including the mailing list address.\n+\n+Make sure to keep everyone involved in the \"Cc:\" field so that they do not have\n+to be subscribed to the mailing list to receive replies.\n+\n+[[do-not-use-mail-followup-to]]\n+== Do Not Use Mail-Followup-To\n+\n+When posting to the mailing list, your email client might add a\n+\"Mail-Followup-To:\" field which contains all of the recipients, including the\n+mailing list address, but not the sender's email address. This is intended to\n+prevent the sender from receiving replies twice, once from the replying person\n+and again from the mailing list.\n+\n+This goes directly against the desired \"To:\" and \"Cc:\" etiquette (see \"Proper\n+Use of To and Cc\" above). Most users want to use \"group reply\" or \"Reply to\n+all\" in their mail client and create a reply email that is sent directly to\n+author of the email they are replying to with all other recipients, as well as\n+the mailing list address, in the \"Cc:\" field.\n+\n+The proper thing to do is to never use the \"Mail-Followup-To:\" field as well as\n+disable honoring any \"Mail-Followup-To:\" fields in any emails you reply to.\n+Some email clients come with both enabled by default. Mutt is like this (see\n+Disable Mail-Followup-To in the Mutt section below).\n+\n+[[enable-plain-text-mode]]\n+== Enable Plain Text Mode\n+\n+Most email clients automatically reject mailing list email if it is not a\n+text/plain formatted email. For that reason, it is important that your email\n+client is set to create text/plain emails instead of text/enriched or\n+text/html email.\n+\n+[[patches-that-receive-no-response]]\n+\n+From Junio's notes from the maintainer:\n+\n+> If you sent a patch and you did not hear any response from anybody for\n+> several days, it could be that your patch was totally uninteresting,\n+> but it also is possible that it was simply lost in the noise. Please\n+> do not hesitate to send a reminder message in such a case. Messages\n+> getting lost in the noise may be a sign that those who can evaluate\n+> your patch don't have enough mental/time bandwidth to process them\n+> right at the moment, and it often helps to wait until the list traffic\n+> becomes calmer before sending such a reminder.\n+\n+[[send-merge-ready-patches-to-the-maintainer]]\n+== Send Merge-Ready Patches to the Maintainer\n+\n+Once a patch has achieved consensus and all stakeholders are staisfied and\n+everything is ready for merging, then you send it to the maintainer: \"To:\n+gitster@pobox.com\".\n+\n+[[mutt-config]]\n+== Mutt Config\n+\n+This section has suggestions for how to set up Mutt to be polite.\n+\n+[[known-mailing-lists]]\n+=== Known Mailing Lists\n+\n+Mutt has the ability to change its behavior when replying to a mailing list. For\n+Mutt to know when an address is a mailing list, use the `subscribe` keyword in\n+your Mutt configuration:\n+\n+**~/.muttrc:**\n+```\n+# tell Mutt about the Git mailing list\n+subscribe git@vger.kernel.org\n+```\n+\n+[[reply-properly]]\n+=== Reply Properly\n+\n+By default, Mutt uses the 'g' and 'L' hotkeys to execute a \"group reply\" or\n+\"list reply\" respectively. A \"group reply\" creates an email addressed to the\n+sender with all other recipients in the \"Cc\". A \"list reply\" starts an email\n+addressed only to the mailing list without anybody else as \"Cc\".\n+\n+Per rule X, Y, and Z above, using \"group reply\" in Mutt is what you want to do.\n+\n+[[disable-mail-followup-to]]\n+=== Disable Mail-Followup-To\n+\n+By default, when replying to mailing lists, Mutt will automatically generate\n+\"Mail-Followup-To\" headers. To fix this, disable the generation of the header\n+in your Mutt configuration. It is also a good idea to disable honoring any\n+\"Mail-Followup-To\" headers so that any \"group reply\" operations are correctly\n+addressed.\n+\n+**~/.muttrc:**\n+```\n+# disable Mail-Followup-To header\n+unset followup_to\n+\n+# disable honoring Mail-Followup-To header\n+unset honor_followup_to\n+```\n+\n-- \n2.20.1\n\n"},{"id":"424261","messageId":"20210512025746.GA1899@localhost","threadId":"55667","inReplyTo":"20210512025447.6068-1-dwh@linuxprogrammer.org","subject":"Re: [PATCH v1] Writing down mail list etiquette.","fromName":"Dave Huseby","fromEmail":"dwh@linuxprogrammer.org","sentAt":"2021-05-12T02:57:46Z","receivedAt":"2021-05-12T02:57:49Z","isPatch":true,"sender":{"key":"dwh@linuxprogrammer.org","avatar":null},"body":"Doh! I forgot to make this patch In-Reply-To the previous thread that\nsparked this discussion. Well, at least this patch email doesn't have a\nMail-Followup-To header.\n\nCheers!\nDave\n"},{"id":"424378","messageId":"20210512031821.6498-1-dwh@linuxprogrammer.org","threadId":"55667","inReplyTo":"20210512025447.6068-1-dwh@linuxprogrammer.org","subject":"","fromName":"Dave Huseby","fromEmail":"dwh@linuxprogrammer.org","sentAt":"2021-05-12T03:18:20Z","receivedAt":"2021-05-12T03:18:52Z","isPatch":false,"sender":{"key":"dwh@linuxprogrammer.org","avatar":null},"body":"\nAaaand I forgot to Cc all of the relevant people from the previous\nthread. I also messed up a name and email in the previous commit\nmessages. Both are fixed. It's been a long day :)\n\nCheers!\nDave\n\n"},{"id":"424266","messageId":"20210512031821.6498-2-dwh@linuxprogrammer.org","threadId":"55667","inReplyTo":"20210512031821.6498-1-dwh@linuxprogrammer.org","subject":"[PATCH v2] Writing down mail list etiquette.","fromName":"Dave Huseby","fromEmail":"dwh@linuxprogrammer.org","sentAt":"2021-05-12T03:18:21Z","receivedAt":"2021-05-12T03:18:53Z","isPatch":true,"sender":{"key":"dwh@linuxprogrammer.org","avatar":null},"body":"After violating a few unspoken etiquette rules that were spotted by\nChristian Couder , Filipe Contreras\n suggested that somebody write a guide.\nSince I was the latest cause of this perenial discussion, I took it upon\nmyself to learn from my mistakes and document the fixes.\n\nThanks to Junio for providing links to similar\ndiscussions in the past and Stefan Moch for\npointing out where the related documentation already existed in the\ntree.\n\nSigned-off-by: Dave Huseby \n---\n Documentation/MailingListEtiquette.txt | 125 +++++++++++++++++++++++++\n 1 file changed, 125 insertions(+)\n create mode 100644 Documentation/MailingListEtiquette.txt\n\ndiff --git a/Documentation/MailingListEtiquette.txt b/Documentation/MailingListEtiquette.txt\nnew file mode 100644\nindex 0000000000..9da2d490aa\n--- /dev/null\n+++ b/Documentation/MailingListEtiquette.txt\n@@ -0,0 +1,125 @@\n+Mailing List Etiquette\n+======================\n+\n+[[introduction]]\n+== Introduction\n+\n+Open source, community projects such as Git use a mailing list and email to\n+coordinate development and to submit patches for review. This article documents\n+the unspoken rules and etiquette for the proper way to send email to the\n+mailing list. What follows are considered best practices to follow.\n+\n+If you are looking for details on how to submit a patch, that is documented\n+elsewhere in:\n+\n+- `Documentation/SubmittingPatches`\n+- `Documentation/MyFirstContribution.txt`\n+\n+[[proper-use-of-to-and-cc]]\n+== Proper Use of To and Cc\n+\n+When starting a new email thread that is not directed at any specific person,\n+put the mailing list address in the \"To:\" field, otherwise address it to the\n+person and put the mailing list address in the \"Cc:\" field.\n+\n+When replying to an email on the mailing list, put the person you are replying\n+to in the \"To:\" field and all other people in the thread in the \"Cc:\" field,\n+including the mailing list address.\n+\n+Make sure to keep everyone involved in the \"Cc:\" field so that they do not have\n+to be subscribed to the mailing list to receive replies.\n+\n+[[do-not-use-mail-followup-to]]\n+== Do Not Use Mail-Followup-To\n+\n+When posting to the mailing list, your email client might add a\n+\"Mail-Followup-To:\" field which contains all of the recipients, including the\n+mailing list address, but not the sender's email address. This is intended to\n+prevent the sender from receiving replies twice, once from the replying person\n+and again from the mailing list.\n+\n+This goes directly against the desired \"To:\" and \"Cc:\" etiquette (see \"Proper\n+Use of To and Cc\" above). Most users want to use \"group reply\" or \"Reply to\n+all\" in their mail client and create a reply email that is sent directly to\n+author of the email they are replying to with all other recipients, as well as\n+the mailing list address, in the \"Cc:\" field.\n+\n+The proper thing to do is to never use the \"Mail-Followup-To:\" field as well as\n+disable honoring any \"Mail-Followup-To:\" fields in any emails you reply to.\n+Some email clients come with both enabled by default. Mutt is like this (see\n+Disable Mail-Followup-To in the Mutt section below).\n+\n+[[enable-plain-text-mode]]\n+== Enable Plain Text Mode\n+\n+Most email clients automatically reject mailing list email if it is not a\n+text/plain formatted email. For that reason, it is important that your email\n+client is set to create text/plain emails instead of text/enriched or\n+text/html email.\n+\n+[[patches-that-receive-no-response]]\n+\n+From Junio's notes from the maintainer:\n+\n+> If you sent a patch and you did not hear any response from anybody for\n+> several days, it could be that your patch was totally uninteresting,\n+> but it also is possible that it was simply lost in the noise. Please\n+> do not hesitate to send a reminder message in such a case. Messages\n+> getting lost in the noise may be a sign that those who can evaluate\n+> your patch don't have enough mental/time bandwidth to process them\n+> right at the moment, and it often helps to wait until the list traffic\n+> becomes calmer before sending such a reminder.\n+\n+[[send-merge-ready-patches-to-the-maintainer]]\n+== Send Merge-Ready Patches to the Maintainer\n+\n+Once a patch has achieved consensus and all stakeholders are staisfied and\n+everything is ready for merging, then you send it to the maintainer: \"To:\n+gitster@pobox.com\".\n+\n+[[mutt-config]]\n+== Mutt Config\n+\n+This section has suggestions for how to set up Mutt to be polite.\n+\n+[[known-mailing-lists]]\n+=== Known Mailing Lists\n+\n+Mutt has the ability to change its behavior when replying to a mailing list. For\n+Mutt to know when an address is a mailing list, use the `subscribe` keyword in\n+your Mutt configuration:\n+\n+**~/.muttrc:**\n+```\n+# tell Mutt about the Git mailing list\n+subscribe git@vger.kernel.org\n+```\n+\n+[[reply-properly]]\n+=== Reply Properly\n+\n+By default, Mutt uses the 'g' and 'L' hotkeys to execute a \"group reply\" or\n+\"list reply\" respectively. A \"group reply\" creates an email addressed to the\n+sender with all other recipients in the \"Cc\". A \"list reply\" starts an email\n+addressed only to the mailing list without anybody else as \"Cc\".\n+\n+Per rule X, Y, and Z above, using \"group reply\" in Mutt is what you want to do.\n+\n+[[disable-mail-followup-to]]\n+=== Disable Mail-Followup-To\n+\n+By default, when replying to mailing lists, Mutt will automatically generate\n+\"Mail-Followup-To\" headers. To fix this, disable the generation of the header\n+in your Mutt configuration. It is also a good idea to disable honoring any\n+\"Mail-Followup-To\" headers so that any \"group reply\" operations are correctly\n+addressed.\n+\n+**~/.muttrc:**\n+```\n+# disable Mail-Followup-To header\n+unset followup_to\n+\n+# disable honoring Mail-Followup-To header\n+unset honor_followup_to\n+```\n+\n-- \n2.20.1\n\n"},{"id":"424272","messageId":"80e0215a-cd00-57f9-afb6-b85b33dba91d@gmail.com","threadId":"55667","inReplyTo":"20210512031821.6498-2-dwh@linuxprogrammer.org","subject":"Re: [PATCH v2] Writing down mail list etiquette.","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-05-12T04:07:55Z","receivedAt":"2021-05-12T04:08:01Z","isPatch":true,"sender":{"key":"bagasdotme@gmail.com","avatar":"https://avatars.githubusercontent.com/u/40219486?v=4"},"body":"On 12/05/21 10.18, Dave Huseby wrote:\n> After violating a few unspoken etiquette rules that were spotted by\n> Christian Couder , Filipe Contreras\n> suggested that somebody write a guide.\n> Since I was the latest cause of this perenial discussion, I took it upon\n> myself to learn from my mistakes and document the fixes.\n> \n> Thanks to Junio for providing links to similar\n> discussions in the past and Stefan Moch for\n> pointing out where the related documentation already existed in the\n> tree.\n> \n> Signed-off-by: Dave Huseby \n> ---\n> Documentation/MailingListEtiquette.txt | 125 +++++++++++++++++++++++++\n> 1 file changed, 125 insertions(+)\n> create mode 100644 Documentation/MailingListEtiquette.txt\n> \n> diff --git a/Documentation/MailingListEtiquette.txt b/Documentation/MailingListEtiquette.txt\n> new file mode 100644\n> index 0000000000..9da2d490aa\n> --- /dev/null\n> +++ b/Documentation/MailingListEtiquette.txt\n> @@ -0,0 +1,125 @@\n> +Mailing List Etiquette\n> +======================\n> +\n> +[[introduction]]\n> +== Introduction\n> +\n> +Open source, community projects such as Git use a mailing list and email to\n> +coordinate development and to submit patches for review. This article documents\n> +the unspoken rules and etiquette for the proper way to send email to the\n> +mailing list. What follows are considered best practices to follow.\n> +\n\nBut not all open source projects use mailing lists. Most (but not all, also\nexcluding Git) projects use Pull Requests (PR) as a way to submit patches and\nfor review.\n\nOf course, some projects that use PR also coordinate their development using\nmailing lists, patches submissions are done the other way.\n\nSo we can say \"Several (but not all) open source, community projects such as\nGit use a mailing list to coordinate development AND to submit patches for\nreview\". Note the emphasized AND.\n\n> +If you are looking for details on how to submit a patch, that is documented\n> +elsewhere in:\n> +\n> +- `Documentation/SubmittingPatches`\n> +- `Documentation/MyFirstContribution.txt`\n> +\n> +[[proper-use-of-to-and-cc]]\n> +== Proper Use of To and Cc\n> +\n> +When starting a new email thread that is not directed at any specific person,\n> +put the mailing list address in the \"To:\" field, otherwise address it to the\n> +person and put the mailing list address in the \"Cc:\" field.\n> +\n> +When replying to an email on the mailing list, put the person you are replying\n> +to in the \"To:\" field and all other people in the thread in the \"Cc:\" field,\n> +including the mailing list address.\n> +\n> +Make sure to keep everyone involved in the \"Cc:\" field so that they do not have\n> +to be subscribed to the mailing list to receive replies.\n> +\n> +[[do-not-use-mail-followup-to]]\n> +== Do Not Use Mail-Followup-To\n> +\n> +When posting to the mailing list, your email client might add a\n> +\"Mail-Followup-To:\" field which contains all of the recipients, including the\n> +mailing list address, but not the sender's email address. This is intended to\n> +prevent the sender from receiving replies twice, once from the replying person\n> +and again from the mailing list.\n> +\n> +This goes directly against the desired \"To:\" and \"Cc:\" etiquette (see \"Proper\n> +Use of To and Cc\" above). Most users want to use \"group reply\" or \"Reply to\n> +all\" in their mail client and create a reply email that is sent directly to\n> +author of the email they are replying to with all other recipients, as well as\n> +the mailing list address, in the \"Cc:\" field.\n> +\n> +The proper thing to do is to never use the \"Mail-Followup-To:\" field as well as\n> +disable honoring any \"Mail-Followup-To:\" fields in any emails you reply to.\n> +Some email clients come with both enabled by default. Mutt is like this (see\n> +Disable Mail-Followup-To in the Mutt section below).\n> +\n\nBetter say \"Some email clients, such as Mutt (see Disable Mail-Followup-To in\nmutt-config section below) come with both enabled by default.\"\n\n> +[[enable-plain-text-mode]]\n> +== Enable Plain Text Mode\n> +\n> +Most email clients automatically reject mailing list email if it is not a\n> +text/plain formatted email. For that reason, it is important that your email\n> +client is set to create text/plain emails instead of text/enriched or\n> +text/html email.\n> +\n> +[[patches-that-receive-no-response]]\n> +\n> +From Junio's notes from the maintainer:\n> +\n> +> If you sent a patch and you did not hear any response from anybody for\n> +> several days, it could be that your patch was totally uninteresting,\n> +> but it also is possible that it was simply lost in the noise. Please\n> +> do not hesitate to send a reminder message in such a case. Messages\n> +> getting lost in the noise may be a sign that those who can evaluate\n> +> your patch don't have enough mental/time bandwidth to process them\n> +> right at the moment, and it often helps to wait until the list traffic\n> +> becomes calmer before sending such a reminder.\n> +\n\nIs \"Review ping\" enough for reminder purpose?\n\n> +[[send-merge-ready-patches-to-the-maintainer]]\n> +== Send Merge-Ready Patches to the Maintainer\n> +\n> +Once a patch has achieved consensus and all stakeholders are staisfied and\n> +everything is ready for merging, then you send it to the maintainer: \"To:\n> +gitster@pobox.com\".\n> +\n\nI see the typo. s/staisfied/satisfied/\n\nLet's say that we had consented that my patch series was deemed ready at\nv5 version. From the paragraph above, I interpreted it as \"now my series\nwas consented ready, I need to send v6 to Junio (current Git maintainer)\".\nIn practice, the maintainer could instead merged v5 (without having me to\nsend v6 [final]), because v5 is merge-ready in absence of maintainer's\nemail address in either To: or Cc:.\n\nOh yeah, should mailing list's address be also in To:/Cc: when sending\nmerge-ready patch series?\n\n> +[[mutt-config]]\n> +== Mutt Config\n> +\n> +This section has suggestions for how to set up Mutt to be polite.\n> +\n\nBetter say \"This section suggests how to set up Mutt to be conformant\nto the etiquette above.\".\n\n> +[[known-mailing-lists]]\n> +=== Known Mailing Lists\n> +\n> +Mutt has the ability to change its behavior when replying to a mailing list. For\n> +Mutt to know when an address is a mailing list, use the `subscribe` keyword in\n> +your Mutt configuration:\n> +\n\nBetter say \"... specify mailing list address on `subscribe` command in your Mutt\nconfiguration:\".\n\n> +**~/.muttrc:**\n> +```\n> +# tell Mutt about the Git mailing list\n> +subscribe git@vger.kernel.org\n> +```\n> +\n> +[[reply-properly]]\n> +=== Reply Properly\n> +\n> +By default, Mutt uses the 'g' and 'L' hotkeys to execute a \"group reply\" or\n> +\"list reply\" respectively. A \"group reply\" creates an email addressed to the\n> +sender with all other recipients in the \"Cc\". A \"list reply\" starts an email\n> +addressed only to the mailing list without anybody else as \"Cc\".\n> +\n> +Per rule X, Y, and Z above, using \"group reply\" in Mutt is what you want to do.\n> +\n> +[[disable-mail-followup-to]]\n> +=== Disable Mail-Followup-To\n> +\n> +By default, when replying to mailing lists, Mutt will automatically generate\n> +\"Mail-Followup-To\" headers. To fix this, disable the generation of the header\n> +in your Mutt configuration. It is also a good idea to disable honoring any\n> +\"Mail-Followup-To\" headers so that any \"group reply\" operations are correctly\n> +addressed.\n> +\n> +**~/.muttrc:**\n> +```\n> +# disable Mail-Followup-To header\n> +unset followup_to\n> +\n> +# disable honoring Mail-Followup-To header\n> +unset honor_followup_to\n> +```\n> +\n> \n\nThanks.\n\n-- \nAn old man doll... just what I always wanted! - Clara\n"},{"id":"424280","messageId":"xmqqa6p0h853.fsf@gitster.g","threadId":"55667","inReplyTo":"20210512031821.6498-2-dwh@linuxprogrammer.org","subject":"Re: [PATCH v2] Writing down mail list etiquette.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-05-12T04:46:00Z","receivedAt":"2021-05-12T04:46:04Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Dave Huseby writes:\n\n> +Mailing List Etiquette\n> +======================\n> +\n> +[[introduction]]\n> +== Introduction\n> +\n> +Open source, community projects such as Git use a mailing list and email to\n> +coordinate development and to submit patches for review. This article documents\n> +the unspoken rules and etiquette for the proper way to send email to the\n> +mailing list. What follows are considered best practices to follow.\n\nPlease ensure that we do *not* sound like dictating our rules on\nbroader open-source community. The document merely talks about the\nrules followed in _our_ community (iow, git@vger.kernel.org mailing\nlist).\n\n> +[[proper-use-of-to-and-cc]]\n> +== Proper Use of To and Cc\n> +\n> +When starting a new email thread that is not directed at any specific person,\n> +put the mailing list address in the \"To:\" field, otherwise address it to the\n> +person and put the mailing list address in the \"Cc:\" field.\n> +\n> +When replying to an email on the mailing list, put the person you are replying\n> +to in the \"To:\" field and all other people in the thread in the \"Cc:\" field,\n> +including the mailing list address.\n\nThe above two say \"do X\" but lack \"because Y\".\n\nEven when starting a new discussion thread, it is perfectly fine to\nhave specific people on To: while keeping general community members\nin the loop by CC:ing the list. You'd summon area expert that way.\n\nI think the above two items can be viewed from a different angle as\na mere consequence of a single guiding principle. \n\n\"To:\" is the place to list the people you want to directly interact\nwith and request responses from, and \"Cc:\" is for other people, to\nwhom you would want to inform this conversation is going on, but you\ndo not necessarily need to hear their opinion from (they are of\ncourse welcome to chime in).\n\nAnd as a consequence of that, the two rules you wrote will fall out\nnaturally. If you have people in mind that you want to directly\ntalk to and/or expect their reaction from, list them on \"To\";\neverybody else goes to \"Cc:'. When there is no particular person to\ntalk to, the mailing list address is a good catch-all address to\nreach everybody, hoping there may be some people who are interested\nenough to respond.\n\nThe above is the \"do X\" part. We need to explain why we want\nreaders to do so, i.e. \"because Y\".\n\n This allows recipients to prioritize their incoming messages;\n they can direct their immediate attention to those messages with\n their names on the To: field and the ones with their names on the\n Cc: field can wait.\n\n> +Make sure to keep everyone involved in the \"Cc:\" field so that they do not have\n> +to be subscribed to the mailing list to receive replies.\n\nThis one has both \"do X, because Y\". Good.\n\n> +[[do-not-use-mail-followup-to]]\n> +== Do Not Use Mail-Followup-To\n> +\n> +When posting to the mailing list, your email client might add a\n> +\"Mail-Followup-To:\" field which contains all of the recipients, including the\n> +mailing list address, but not the sender's email address. This is intended to\n> +prevent the sender from receiving replies twice, once from the replying person\n> +and again from the mailing list.\n> +\n> +This goes directly against the desired \"To:\" and \"Cc:\" etiquette (see \"Proper\n> +Use of To and Cc\" above).\n\n... because \"Reply to all\" will redirect the response to all the\nfolks that were originally on \"cc:\", instead of going to the person\nwho sent the message that is being responded to.\n\n> Most users want to use \"group reply\" or \"Reply to\n> +all\" in their mail client and create a reply email that is sent directly to\n> +author of the email they are replying to with all other recipients, as well as\n> +the mailing list address, in the \"Cc:\" field.\n> +\n> +The proper thing to do is to never use the \"Mail-Followup-To:\" field as well as\n> +disable honoring any \"Mail-Followup-To:\" fields in any emails you reply to.\n> +Some email clients come with both enabled by default. Mutt is like this (see\n> +Disable Mail-Followup-To in the Mutt section below).\n> +\n> +[[enable-plain-text-mode]]\n> +== Enable Plain Text Mode\n> +\n> +Most email clients automatically reject mailing list email if it is not a\n> +text/plain formatted email.\n\nIs this true? I know that _our_ mailing list will reject text/html\ne-mail and that is why we ask people to send text/plain e-mails. I\ndoubt that some/many/most clients reject non text messages.\n\n> +For that reason, it is important that your email\n> +client is set to create text/plain emails instead of text/enriched or\n> +text/html email.\n> +\n> +[[patches-that-receive-no-response]]\n> +\n> +From Junio's notes from the maintainer:\n> +\n> +> If you sent a patch and you did not hear any response from anybody for\n> +> several days, it could be that your patch was totally uninteresting,\n> +> but it also is possible that it was simply lost in the noise. Please\n> +> do not hesitate to send a reminder message in such a case. Messages\n> +> getting lost in the noise may be a sign that those who can evaluate\n> +> your patch don't have enough mental/time bandwidth to process them\n> +> right at the moment, and it often helps to wait until the list traffic\n> +> becomes calmer before sending such a reminder.\n> +\n> +[[send-merge-ready-patches-to-the-maintainer]]\n> +== Send Merge-Ready Patches to the Maintainer\n> +\n> +Once a patch has achieved consensus and all stakeholders are staisfied and\n> +everything is ready for merging, then you send it to the maintainer: \"To:\n> +gitster@pobox.com\".\n\nThis needs to be cc'ed to the list. But I am not sure if it needs\nto be duplicated in this document. Practically nobody seems to do\nthis and expect me to pick things up instead.\n\n\n"},{"id":"424284","messageId":"609b73cbf39ab_6d897208a8@natae.notmuch","threadId":"55667","inReplyTo":"20210512025447.6068-1-dwh@linuxprogrammer.org","subject":"RE: [PATCH v1] Writing down mail list etiquette.","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-12T06:21:00Z","receivedAt":"2021-05-12T06:21:08Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Dave Huseby wrote:\n> After violating a few unspoken etiquette rules that were spotted by\n> Christian Couder , Filipe Contreras\n> suggested that somebody write a guide.\n\nThanks for doing this. It's hard for seasoned developers to spot the\ngaps in documentation, and that's why it's so important for newcomers to\nfill them before they themselve get too accustomed with the project.\n\n> --- /dev/null\n> +++ b/Documentation/MailingListEtiquette.txt\n> @@ -0,0 +1,125 @@\n> +Mailing List Etiquette\n> +======================\n> +\n> +[[introduction]]\n> +== Introduction\n> +\n> +Open source, community projects such as Git use a mailing list and email to\n> +coordinate development and to submit patches for review. This article documents\n> +the unspoken rules and etiquette for the proper way to send email to the\n> +mailing list. What follows are considered best practices to follow.\n\n Some open source projects--such as Git--use email to...\n\nSome open source projects do, certainly not all.\n\n> +If you are looking for details on how to submit a patch, that is documented\n> +elsewhere in:\n> +\n> +- `Documentation/SubmittingPatches`\n> +- `Documentation/MyFirstContribution.txt`\n> +\n> +[[proper-use-of-to-and-cc]]\n> +== Proper Use of To and Cc\n> +\n> +When starting a new email thread that is not directed at any specific person,\n> +put the mailing list address in the \"To:\" field, otherwise address it to the\n> +person and put the mailing list address in the \"Cc:\" field.\n> +\n> +When replying to an email on the mailing list, put the person you are replying\n> +to in the \"To:\" field and all other people in the thread in the \"Cc:\" field,\n> +including the mailing list address.\n> +\n> +Make sure to keep everyone involved in the \"Cc:\" field so that they do not have\n> +to be subscribed to the mailing list to receive replies.\n\nAlthough all this is OK, I don't think it matters much who you put in\nCc, and who in the To fields.\n\nAs long as everyone involved--including the mailing list--is in both\nfields, you are fine.\n\n> +[[do-not-use-mail-followup-to]]\n> +== Do Not Use Mail-Followup-To\n\nEr, this is improtant, but it shouldn't be #2.\n\nThere's a lot of things more important than this, for example something\nI encountered recently...\n\n Do not top-post [1], and try to remove as much context as possible.\n Only leave the context that is important for your reply.\n\nIn fact, this opens the possiblity for some much needed levity...\n\n A: Because it messes up the order in which people normally read text.\n Q: Why is top-posting such a bad thing?\n A: Top-posting.\n Q: What is the most annoying thing in e-mail?\n\nThis is especially important for people coming from corporate\nenvironments where top-posting is the norm, and no context is ever\ndeleted.\n\n[1] https://en.wikipedia.org/wiki/Posting_style#Interleaved_style\n\n> +[[enable-plain-text-mode]]\n> +== Enable Plain Text Mode\n> +\n> +Most email clients automatically reject mailing list email if it is not a\n> +text/plain formatted email.\n\nIt's not the email clients, it's the mailing list software itself.\n\nEither way this is important.\n\n> +[[patches-that-receive-no-response]]\n> +\n> +From Junio's notes from the maintainer:\n> +\n> +> If you sent a patch and you did not hear any response from anybody for\n> +> several days, it could be that your patch was totally uninteresting,\n> +> but it also is possible that it was simply lost in the noise. Please\n> +> do not hesitate to send a reminder message in such a case. Messages\n> +> getting lost in the noise may be a sign that those who can evaluate\n> +> your patch don't have enough mental/time bandwidth to process them\n> +> right at the moment, and it often helps to wait until the list traffic\n> +> becomes calmer before sending such a reminder.\n\nThis is important for other mails, like bug reports, and questions, not\njust patches.\n\n\nAnother very general aspect of the git mailing list (and others\nsimilar), is that you should never be afraid of simply sending a\npoint-blank mail to the mailinsg list.\n\nYou don't need to subscribe, and you don't need to look for people to\nCc... Just send the mail.\n\nIt's generally better to just send the mail than not send it (even if\npeople like Dave are bitten by their configuration).\n\nCheers.\n\n-- \nFelipe Contreras\n"},{"id":"424287","messageId":"609b74dd87714_6d8972089f@natae.notmuch","threadId":"55667","inReplyTo":"20210512025746.GA1899@localhost","subject":"Re: [PATCH v1] Writing down mail list etiquette.","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-12T06:25:33Z","receivedAt":"2021-05-12T06:25:40Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Dave Huseby wrote:\n> Doh! I forgot to make this patch In-Reply-To the previous thread that\n> sparked this discussion. Well, at least this patch email doesn't have a\n> Mail-Followup-To header.\n\nAhh, that reminds me of another point I wanted to raise.\n\n\nIn general people should try to start new threads rather than recycle\nold ones (unless specifically necessary).\n\nI suspect this is contentious at this point, but I personally belive\nthis is the way to go.\n\nIf people align with my view, then you did the correct thing by starting\na new thread rather than using In-Reply-To. We'll see.\n\n-- \nFelipe Contreras\n"},{"id":"424290","messageId":"609b797a818bb_6d897208ce@natae.notmuch","threadId":"55667","inReplyTo":"80e0215a-cd00-57f9-afb6-b85b33dba91d@gmail.com","subject":"Re: [PATCH v2] Writing down mail list etiquette.","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-12T06:45:14Z","receivedAt":"2021-05-12T06:45:21Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Bagas Sanjaya wrote:\n> Let's say that we had consented that my patch series was deemed ready at\n> v5 version. From the paragraph above, I interpreted it as \"now my series\n> was consented ready, I need to send v6 to Junio (current Git maintainer)\".\n> In practice, the maintainer could instead merged v5 (without having me to\n> send v6 [final]), because v5 is merge-ready in absence of maintainer's\n> email address in either To: or Cc:.\n\nYes and no.\n\nConsensus, mearge-ready status, and merged, are three very diffent\nconcepts. Generally they are one-and-the-same, but not always.\n\n 1. A patch can have consensus, and yet Junio doesn't merge it\n 2. A patch may not have consensus, and yet Junio merges it\n 3. A patch may be merge-ready, no consensus, and yet merged\n 4. A patch may be merge-ready, no consensus, and unmerged\n ...\n\nI'm not going through every combination... You get the point.\n\n\nGenerally you don't need to worry about this, that's Junio's job. If\nyour patch is ready, Junio will merge it... But not always.\n\nSo no, you don't need to send v6, Junio will pick v5. If he doesn't,\nit's most likely because it slipped through the cracks, and you can see\nthat in the next \"What's cooking in git.git\".\n\nIf you don't see your merge-ready patch series in \"what's cooking\", then\nby all means send it again as v6, or reply to the \"what's cooking\" or\nsomething. But generally there's no point in sending a v6 identical to a\nv5.\n\nJust poke Junio.\n\n> Oh yeah, should mailing list's address be also in To:/Cc: when sending\n> merge-ready patch series?\n\nIMO the maxim should be: if it's relevant to git, send it to to the git\nmailing list... *Always*... Don't ever hesitate.\n\nBut if you already sent a v5 that is is merge-ready, there's no need\nto send an identical v6.\n\n\nAll these suggestions are of course based on my own experience. Others\nmight have different experiences.\n\nCheers.\n\n-- \nFelipe Contreras\n"},{"id":"424296","messageId":"CAPig+cQvnsRe0fdPaBe9hJ4LbPFmHmGVNdiGYLqi2JM7A5GmjA@mail.gmail.com","threadId":"55667","inReplyTo":"609b797a818bb_6d897208ce@natae.notmuch","subject":"Re: [PATCH v2] Writing down mail list etiquette.","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2021-05-12T07:35:32Z","receivedAt":"2021-05-12T07:35:47Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Wed, May 12, 2021 at 2:45 AM Felipe Contreras\n wrote:\n> Bagas Sanjaya wrote:\n> > In practice, the maintainer could instead merged v5 (without having me to\n> > send v6 [final]), because v5 is merge-ready in absence of maintainer's\n> > email address in either To: or Cc:.\n>\n> Generally you don't need to worry about this, that's Junio's job. If\n> your patch is ready, Junio will merge it... But not always.\n>\n> So no, you don't need to send v6, Junio will pick v5. If he doesn't,\n> it's most likely because it slipped through the cracks, and you can see\n> that in the next \"What's cooking in git.git\".\n>\n> If you don't see your merge-ready patch series in \"what's cooking\", then\n> by all means send it again as v6, or reply to the \"what's cooking\" or\n> something. But generally there's no point in sending a v6 identical to a\n> v5.\n>\n> But if you already sent a v5 that is is merge-ready, there's no need\n> to send an identical v6.\n>\n> All these suggestions are of course based on my own experience. Others\n> might have different experiences.\n\nThis has been my experience, as well. I've never sent a v6 with Junio\nas an explicit recipient, but which was otherwise identical to v5.\n\nAnother reason to avoid sending v6 which is identical to v5 is that it\npotentially wastes reviewer bandwidth.\n\nThe advice which seems to have triggered this particular discussion\ncomes from Documentation/SubmittingPatches:\n\n After the list reached a consensus that it is a good idea to\n apply the patch, re-send it with \"To:\" set to the\n maintainer{current-maintainer} and \"cc:\" the list{git-ml} for\n inclusion. This is especially relevant when the maintainer did\n not heavily participate in the discussion and instead left the\n review to trusted others.\n\nIt's not the first time this advice has resulted in confusion. Perhaps\nnow would a good time to retire it altogether, or at least rewrite it\nto mention the points you gave above about responding to \"What's\nCooking\" or by sending a \"ping\" to the original patch email (which may\nresult in Junio either picking up the patch or responding with an\nexplanation as to why he didn't).\n\nFollowing the above SubmittingPatches paragraph is another which also\nseems to mislead people frequently:\n\n Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:`\n and `Tested-by:` lines as necessary to credit people who helped\n your patch, and \"cc:\" them when sending such a final version for\n inclusion.\n\nIn fact, a submitter should almost never add a Reviewed-by: trailer\nbecause Reviewed-by: is explicitly given by a reviewer only when the\nreviewer is satisfied that the patch is merge-ready, in which case no\nmore re-rolls are expected. Instead, these particular trailers are\nalmost always added by Junio based upon reviewer responses he sees\nwhen picking up a patch. So, it may be time, too, either to remove\nthis paragraph or to revise it to mention other trailers more\nappropriate for use by the patch submitter, such as Helped-by:,\nSuggested-by:, perhaps Co-authored-by:, etc.\n"},{"id":"424300","messageId":"609b928aeb66e_6e4e9208b7@natae.notmuch","threadId":"55667","inReplyTo":"CAPig+cQvnsRe0fdPaBe9hJ4LbPFmHmGVNdiGYLqi2JM7A5GmjA@mail.gmail.com","subject":"Re: [PATCH v2] Writing down mail list etiquette.","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-12T08:32:10Z","receivedAt":"2021-05-12T08:32:25Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Eric Sunshine wrote:\n> On Wed, May 12, 2021 at 2:45 AM Felipe Contreras\n> wrote:\n> > Bagas Sanjaya wrote:\n> > > In practice, the maintainer could instead merged v5 (without having me to\n> > > send v6 [final]), because v5 is merge-ready in absence of maintainer's\n> > > email address in either To: or Cc:.\n> >\n> > Generally you don't need to worry about this, that's Junio's job. If\n> > your patch is ready, Junio will merge it... But not always.\n> >\n> > So no, you don't need to send v6, Junio will pick v5. If he doesn't,\n> > it's most likely because it slipped through the cracks, and you can see\n> > that in the next \"What's cooking in git.git\".\n> >\n> > If you don't see your merge-ready patch series in \"what's cooking\", then\n> > by all means send it again as v6, or reply to the \"what's cooking\" or\n> > something. But generally there's no point in sending a v6 identical to a\n> > v5.\n> >\n> > But if you already sent a v5 that is is merge-ready, there's no need\n> > to send an identical v6.\n> >\n> > All these suggestions are of course based on my own experience. Others\n> > might have different experiences.\n> \n> This has been my experience, as well. I've never sent a v6 with Junio\n> as an explicit recipient, but which was otherwise identical to v5.\n> \n> Another reason to avoid sending v6 which is identical to v5 is that it\n> potentially wastes reviewer bandwidth.\n> \n> The advice which seems to have triggered this particular discussion\n> comes from Documentation/SubmittingPatches:\n> \n> After the list reached a consensus that it is a good idea to\n> apply the patch, re-send it with \"To:\" set to the\n> maintainer{current-maintainer} and \"cc:\" the list{git-ml} for\n> inclusion. This is especially relevant when the maintainer did\n> not heavily participate in the discussion and instead left the\n> review to trusted others.\n> \n> It's not the first time this advice has resulted in confusion. Perhaps\n> now would a good time to retire it altogether, or at least rewrite it\n> to mention the points you gave above about responding to \"What's\n> Cooking\" or by sending a \"ping\" to the original patch email (which may\n> result in Junio either picking up the patch or responding with an\n> explanation as to why he didn't).\n\nAgreed.\n\n(Although sometimes a patch series of mine has actually received\nconsensus, and yet for some reason Junio does not pick it up. Except\nin that case sending a v6 certainly would not improve the situation. Not\nsure if that's specific to me though.)\n\n> Following the above SubmittingPatches paragraph is another which also\n> seems to mislead people frequently:\n> \n> Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:`\n> and `Tested-by:` lines as necessary to credit people who helped\n> your patch, and \"cc:\" them when sending such a final version for\n> inclusion.\n> \n> In fact, a submitter should almost never add a Reviewed-by: trailer\n> because Reviewed-by: is explicitly given by a reviewer only when the\n> reviewer is satisfied that the patch is merge-ready, in which case no\n> more re-rolls are expected. Instead, these particular trailers are\n> almost always added by Junio based upon reviewer responses he sees\n> when picking up a patch.\n\nI don't fully agree with that comment.\n\nAt least me personally if I see people acking v5, I add them to v6 as\nReviewed-By.\n\nI'm not sure if that makes any difference to Junio, but that's what I've\nhistorically done.\n\nCheers.\n\n-- \nFelipe Contreras\n"},{"id":"424305","messageId":"871ractjm1.fsf@evledraar.gmail.com","threadId":"55667","inReplyTo":"20210512031821.6498-2-dwh@linuxprogrammer.org","subject":"Re: [PATCH v2] Writing down mail list etiquette.","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-05-12T08:45:39Z","receivedAt":"2021-05-12T08:57:30Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Tue, May 11 2021, Dave Huseby wrote:\n\n> After violating a few unspoken etiquette rules that were spotted by\n> Christian Couder , Filipe Contreras\n> suggested that somebody write a guide.\n> Since I was the latest cause of this perenial discussion, I took it upon\n> myself to learn from my mistakes and document the fixes.\n>\n> Thanks to Junio for providing links to similar\n> discussions in the past and Stefan Moch for\n> pointing out where the related documentation already existed in the\n> tree.\n\nImprovements in this area are most needed, so thanks for working on\nthis.\n\nWe should not have a new file describing this though, we already cover\nthe content you're adding here partially in\nDocumentation/SubmittingPatches, and some more in\nDocumentation/MyFirstContribution.txt (e.g. a passing mention of\nin-reply-to etiquette), with this applied we'd have discussion of these\nrelated topics in three places.\n\nI had some rough WIP patches to update Documentation/SubmittingPatches\nto address some of what you're adding here, which I've discarded, but I\nsubmitted some related patches just now as [1].\n\nAs you can see from that topic we e.g. already have MUA-specific tips in\nDocumentation/SubmittingPatches, your addition of a section discussing\nmutt's config here is another thing we'd be duplicating/unnecessarily\nsplitting across multiple places.\n\nI do think it's going to be hard to update SubmittingPatches, for\nexample it has a long section going on about the specific format of\npatches to craft for the ML, as if anyone's using anything other than\ngit-format-patch these days (it was written before that existed/was as\nestablished).\n\nI suspect though that any suggestion to simply remove most/all of that\nfor simplicity will probably be met with (IMO unwarranted resistance),\nwhich is why I gave up on this the other day before even submitting\npatches to the ML.\n\nBut regardless of that, the post-image after your patch of having\nanother place we discuss the same/related topic would be worse, we\nreally should have one canonical guide, so your patch(es) should be\namending/splitting Documentation/SubmittingPatches, not duplicating it.\n\n1. https://lore.kernel.org/git/cover-0.3-0000000000-20210512T084137Z-avarab@gmail.com/\n"},{"id":"424342","messageId":"xmqqbl9gf299.fsf@gitster.g","threadId":"55667","inReplyTo":"CAPig+cQvnsRe0fdPaBe9hJ4LbPFmHmGVNdiGYLqi2JM7A5GmjA@mail.gmail.com","subject":"Re: [PATCH v2] Writing down mail list etiquette.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-05-12T14:36:02Z","receivedAt":"2021-05-12T14:36:07Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Eric Sunshine writes:\n\n> This has been my experience, as well. I've never sent a v6 with Junio\n> as an explicit recipient, but which was otherwise identical to v5.\n\nIt mostly is because I've been too helpful than the written rule to\nproactively pick up v5, before the participants of the discussion\nexplicitly reaches concensus that it is good enough.\n\nIn an ideal world, patches in areas that I do not have particular\ninterest in and that other reviewers with good taste are performing\ngood reviews, I should be able to keep myself completely out of the\npicture, not involved in their review discussion in any way, and not\neven having to monitor if the discussion reached some concensus, and\npurely play a patch-monkey for such patches. That, combined with\nmore reviewers with good tastes, would allow us to injest patches at\nfaster rate than we currently can.\n\n> Another reason to avoid sending v6 which is identical to v5 is that it\n> potentially wastes reviewer bandwidth.\n\nAs long as it is marked as \"this is the final version that is\nidentical to the previous round, only difference from which is that\nthe collected reviewed-by and acked-by have been added\", it would\nnot waste reviewer bandwidth. The reviewers _should_ however notice\nif it has questionable changes since the \"previous round\", in which\ncase their reviewed-by's may now be invalid, of course, though.\n\n> The advice which seems to have triggered this particular discussion\n> comes from Documentation/SubmittingPatches:\n>\n> After the list reached a consensus that it is a good idea to\n> apply the patch, re-send it with \"To:\" set to the\n> maintainer{current-maintainer} and \"cc:\" the list{git-ml} for\n> inclusion. This is especially relevant when the maintainer did\n> not heavily participate in the discussion and instead left the\n> review to trusted others.\n>\n> It's not the first time this advice has resulted in confusion. Perhaps\n> now would a good time to retire it altogether, or at least rewrite it\n> to mention the points you gave above about responding to \"What's\n> Cooking\" or by sending a \"ping\" to the original patch email (which may\n> result in Junio either picking up the patch or responding with an\n> explanation as to why he didn't).\n\nNo, please do not put _more_ tasks on my plate.\n\nThe \"send the final with everybody's concensus\" is an ideal that\ntries to reduce the maintainer bottleneck by distributing the work\nof final validation. I've been too helpful in this area in that I\nhave often been the one who does the \"ping\" (\"What is the status of\nthis topic?\"), but that would _not_ scale. Anything that the party\nwith more numbers, namely the contributors, can do, we should farm\nit out to them.\n\n> Following the above SubmittingPatches paragraph is another which also\n> seems to mislead people frequently:\n>\n> Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:`\n> and `Tested-by:` lines as necessary to credit people who helped\n> your patch, and \"cc:\" them when sending such a final version for\n> inclusion.\n>\n> In fact, a submitter should almost never add a Reviewed-by: trailer\n> because Reviewed-by: is explicitly given by a reviewer only when the\n> reviewer is satisfied that the patch is merge-ready, in which case no\n> more re-rolls are expected.\n\nYes, that is exactly why v6 that is identical to v5 that all\nreviewers are happy with is useful. It should be able to carry\nreviewed-by's and acked-by's, reviewers can audit that there is no\nforged or otherwise inappropriate reviewed-by's, without placing any\nextra burden on the maintainer.\n\nThanks.\n"},{"id":"424344","messageId":"2db4705a-9062-f74c-43ae-8642d04f3bbb@iee.email","threadId":"55667","inReplyTo":"20210512031821.6498-1-dwh@linuxprogrammer.org","subject":"and... Re: [PATCH v1] Writing down mail list etiquette.","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.email","sentAt":"2021-05-12T15:28:54Z","receivedAt":"2021-05-12T15:37:23Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"On 12/05/2021 04:18, Dave Huseby wrote:\n> Aaaand I forgot to Cc all of the relevant people from the previous\n> thread. I also messed up a name and email in the previous commit\n> messages. Both are fixed. It's been a long day :)\n>\n> Cheers!\n> Dave\n>\nAnd try to ensure the subject is carried in the replies, to avoid\ndeletion as 'junk/spam' (not sure how it happened, just sayin'). I'd\nhesitated to open the email because of the blank subject.\n\nAlso add a note about how to update a subject when a thread has diverged,\ne.g. \"Diverged thread (was: Writing down mail list etiquette).\"\n\nPhilip\n"},{"id":"424401","messageId":"20210512233412.10737-1-dwh@linuxprogrammer.org","threadId":"55667","inReplyTo":"20210512031821.6498-2-dwh@linuxprogrammer.org","subject":"[PATCH v3] doc: writing down Git mailing list etiquette","fromName":"Dave Huseby","fromEmail":"dwh@linuxprogrammer.org","sentAt":"2021-05-12T23:34:12Z","receivedAt":"2021-05-12T23:53:29Z","isPatch":true,"sender":{"key":"dwh@linuxprogrammer.org","avatar":null},"body":"After violating a few unspoken etiquette rules while submitting patches\nto the Git mailing list, it was suggeted that somebody write a guide.\nSince I was the latest cause of this perenial discussion, I took it upon\nmyself to learn from my mistakes and document the Git mailing list\netiquette and the fixes I made to my email setup.\n\n* Add documentation specifically on Git mailing list etiquette\n* Add alternative actions for patches that receive no response.\n* Add section on submitting a final, merge-ready patch.\n* Add section on Mutt MUA settings.\n\nReported-by: Christian Couder \nReported-by: Filipe Contreras \nThanks-to: Junio C Hamano \nThanks-to: Philip Oakley \nThanks-to: Bagas Sanjaya \nThanks-to: Eric Sunshine \nThanks-to: Ævar Arnfjörð Bjarmason \nSigned-off-by: Dave Huseby \n---\n Documentation/MailingListEtiquette.txt | 93 ++++++++++++++++++++++++++\n Documentation/SubmittingPatches | 74 +++++++++++++++++++-\n 2 files changed, 166 insertions(+), 1 deletion(-)\n create mode 100644 Documentation/MailingListEtiquette.txt\n\ndiff --git a/Documentation/MailingListEtiquette.txt b/Documentation/MailingListEtiquette.txt\nnew file mode 100644\nindex 0000000000..8a383f81a8\n--- /dev/null\n+++ b/Documentation/MailingListEtiquette.txt\n@@ -0,0 +1,93 @@\n+Mailing List Etiquette\n+======================\n+\n+[[introduction]]\n+== Introduction\n+\n+The Git project uses a mailing list and email to coordinate development and\n+submit patches. Many other open source projects use web-based forums and pull\n+requests (PRs) to achieve the same thing. This article focuses entirely on the\n+Git project and the etiquette and unspoken rules that have developed over the\n+years. What follows are best practices and suggestions for the \"proper\" way to\n+interact via email on the Git mailing list.\n+\n+If you are looking for details on how to submit a patch, that is documented\n+elsewhere in:\n+\n+- `Documentation/SubmittingPatches`\n+- `Documentation/MyFirstContribution.txt`\n+\n+[[proper-use-of-to-and-cc]]\n+== Proper Use of To and Cc\n+\n+The \"To:\" field is the place to list the people you want to directly interact\n+with and request responses from and the \"Cc:\" field is for other people that\n+you wish to inform of this conversation. Everybody is welcome to chime in on\n+the thread. When there is no particular person you wish to talk to, the mailing\n+list address is a good catch-all addres to reach everybody and should be put in\n+the \"To:\" field.\n+\n+When replying to an email on the mailing list, put the person you are replying\n+to in the \"To:\" field and all other people in the thread in the \"Cc:\" field,\n+including the mailing list address.\n+\n+The motivation for the above suggestions is to allow recipients to prioritize\n+their incoming messages; they can direct their immediate attention to those\n+messages with their names on the \"To:\" field and the ones with their names on\n+the \"Cc:\" field can wait.\n+\n+Make sure to keep everyone involved in the \"Cc:\" field so that they do not have\n+to be subscribed to the mailing list to receive replies.\n+\n+[[proper-use-of-subject]]\n+== Proper Use of the Subject\n+\n+When replying to an email on the list, make sure that the subject of the\n+original email is the subject of your email with \"Re:\" added to it. So if\n+you reply to an email with subject \"first post\", the subject of your email\n+should be \"Re: first post\".\n+\n+Sometimes email threads diverge into other threads about related, but distinct\n+topics. In those cases, the subject like should change to the new topic and\n+include in parenthesis \"(Was: )\". So for instance,\n+if a side thread is created from the \"first post\" thread example, the subject\n+line should be something like \"second post (was: first post)\" with replies\n+having the subject \"Re: second post (was: first post)\".\n+\n+[[use-interleaved-style]]\n+== Use Interleaved Style in Replies\n+\n+> A: Because it messes up the order in which people normally read text.\n+> Q: Why is top-posting such a bad thing?\n+> A: Top-posting.\n+> Q: What is the most annoying thing in email?\n+\n+When replying to emails, use interleaved style which is also sometimes called\n+an \"inline reply\". This creates a natural flow for the reader of the reply. They\n+can easily see what the context for the reply is. Also leave only the context\n+that is important for your reply and delete the rest.\n+\n+[[do-not-use-mail-followup-to]]\n+== Do Not Use Mail-Followup-To\n+\n+When posting to the mailing list, your email client might add a\n+\"Mail-Followup-To:\" field containing all of the recipients, including the\n+mailing list address, but not the sender's email address. This is intended to\n+prevent the sender from receiving replies twice, once from the replying person\n+and again from the mailing list.\n+\n+This goes directly against the desired \"To:\" and \"Cc:\" etiquette (see \"Proper\n+Use of To and Cc\" above) because \"Reply to all\"/\"group reply\" will redirect the\n+response to all of the people in the original \"Cc:\" field instead of going to\n+the person who sent the message being responded to.\n+\n+Some email clients, such as Mutt (see Disable Mail-Followup-To in the Mutt\n+section below) are configured by default to add \"Mail-Followup-To:\" fields and\n+to honor existing \"Mail-Followup-To:\" fields. It is best to disable both.\n+\n+[[enable-plain-text-mode]]\n+== Enable Plain Text Mode\n+\n+The Git mailing list software rejects email sent in text/html format. It is\n+important that your email client is set to create text/plain emails to ensure\n+delivery.\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex 55287d72e0..4f8b9f24ee 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -433,7 +433,7 @@ help you find out who they are.\n \n In any time between the (2)-(3) cycle, the maintainer may pick it up\n from the list and queue it to `seen`, in order to make it easier for\n-people play with it without having to pick up and apply the patch to\n+people to play with it without having to pick up and apply the patch to\n their trees themselves.\n \n [[patch-status]]\n@@ -450,6 +450,46 @@ their trees themselves.\n entitled \"What's cooking in git.git\" and \"What's in git.git\" giving\n the status of various proposed changes.\n \n+[[patches-that-receive-no-response]]\n+== Patches that Receive No Response\n+\n+If you sent a patch and you did not hear any response from anybody for\n+several days, it could be that your patch was totally uninteresting,\n+but it also is possible that it was simply lost in the noise. Please\n+do not hesitate to send a reminder message in such a case. Messages\n+getting lost in the noise may be a sign that those who can evaluate\n+your patch don't have enough mental/time bandwidth to process them\n+right at the moment, and it often helps to wait until the list traffic\n+becomes calmer before sending such a reminder.\n+\n+Alternatives to sending direct reminders are:\n+\n+* Wait for the next \"What's cooking in git.git\" email to see if your patch\n+ series was mentioned and replying to that email with a note pointing out that\n+ your patch series has been overlooked.\n+\n+* Attend the weekly \"stand-up\" meeting held in the \"#git-devel\" channel on\n+ irc.freenode.net and bring it up then.\n+\n+[[send-merge-ready-patches-to-the-maintainer]]\n+== Send Merge-Ready Patches to the Maintainer\n+\n+Once a patch has achieved consensus and all stakeholders are satisfied and\n+everything is ready for merging, you have two main options for getting your\n+patch noticed by the maintainer.\n+\n+1. Submit a new, final, version of the patch with an accurate list of commit\n+ trailers. Make this submission \"To:\" the maintainer, \"In-Reply-To:\" the\n+ previous version of the patch, and add everybody concerned, including the\n+ mailing list address to the \"Cc:\" field. This is a nice way to reduce the\n+ amount of work the maintainer must do to merge the patch while also getting\n+ their attention.\n+\n+2. Creating a \"group reply\"/\"Reply to all\" email to the latest patch series\n+ with the maintainer in the \"To:\" field. This is sometimes referred to as a\n+ \"review ping\" email and is appropriate if the patch requires no more work\n+ and is in its final state with an accurate list of commit trailers.\n+\n [[travis]]\n == GitHub-Travis CI hints\n \n@@ -510,6 +550,38 @@ first patch.\\n\", if you really want to put in the patch e-mail,\n should come after the three-dash line that signals the end of the\n commit message.\n \n+=== Mutt\n+\n+[[known-mailing-lists]]\n+==== Known Mailing Lists\n+\n+Mutt has the ability to change its behavior when replying to a mailing list. You\n+must specify mailing list addresses using the `subscribe` keyword in your Mutt\n+configuration:\n+\n+**~/.muttrc:**\n+```\n+# tell Mutt about the Git mailing list\n+subscribe git@vger.kernel.org\n+```\n+\n+[[disable-mail-followup-to]]\n+==== Disable Mail-Followup-To\n+\n+By default, when replying to mailing lists, Mutt automatically generates\n+\"Mail-Followup-To:\" fields. To fix this, disable the generation of the field\n+in your Mutt configuration. It is also a good idea to disable honoring any\n+\"Mail-Followup-To:\" field so that your \"group reply\" operations are correctly\n+addressed.\n+\n+**~/.muttrc:**\n+```\n+# disable Mail-Followup-To header\n+unset followup_to\n+\n+# disable honoring Mail-Followup-To header\n+unset honor_followup_to\n+```\n \n === Pine\n \n-- \n2.20.1\n\n"},{"id":"424406","messageId":"xmqqy2cjcwn4.fsf@gitster.g","threadId":"55667","inReplyTo":"20210512233412.10737-1-dwh@linuxprogrammer.org","subject":"Re: [PATCH v3] doc: writing down Git mailing list etiquette","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-05-13T00:20:15Z","receivedAt":"2021-05-13T00:22:41Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Dave Huseby writes:\n\n> Documentation/MailingListEtiquette.txt | 93 ++++++++++++++++++++++++++\n> Documentation/SubmittingPatches | 74 +++++++++++++++++++-\n> 2 files changed, 166 insertions(+), 1 deletion(-)\n> create mode 100644 Documentation/MailingListEtiquette.txt\n\nI've read this version over, and did not find much that is\nobjectionable, but as some others said on the previous round, there\nmay be overlaps and repetitions we'd rather get rid of. We should\nbe able to cover discussions around patches in the SubmittingPatches\ndocument without introducing a new document, so all that remains is\nwhat to do with non-patch discussions. I suspect that it might even\nbe sufficient to (1) taylor descriptions introduced in this patch\nfor discussions around patches and reviews, and add it as a new\nsection to SubmittingPatches and (2) mention that the same principle\napplies to non-patch communication in the same section as a sidenote\nbut obviously others may disagree.\n\nÆvar, you also have some updates to SubmittingPatches in flight.\n\nCan I ask you to work with Dave to figure out how well this update\nfits in the entire picture as a stakeholder to the document (i.e.\nnot as \"the guilty party who is involved in conflicts\", but as\n\"somebody who has been long enough to be qualified to guide the\nevolution of the document, and obviously is interested in improving\nthe document\")?\n\nThanks.\n\n\n> diff --git a/Documentation/MailingListEtiquette.txt b/Documentation/MailingListEtiquette.txt\n> new file mode 100644\n> index 0000000000..8a383f81a8\n> --- /dev/null\n> +++ b/Documentation/MailingListEtiquette.txt\n> @@ -0,0 +1,93 @@\n> +Mailing List Etiquette\n> +======================\n> +\n> +[[introduction]]\n> +== Introduction\n> +\n> +The Git project uses a mailing list and email to coordinate development and\n> +submit patches. Many other open source projects use web-based forums and pull\n> +requests (PRs) to achieve the same thing. This article focuses entirely on the\n> +Git project and the etiquette and unspoken rules that have developed over the\n> +years. What follows are best practices and suggestions for the \"proper\" way to\n> +interact via email on the Git mailing list.\n> +\n> +If you are looking for details on how to submit a patch, that is documented\n> +elsewhere in:\n> +\n> +- `Documentation/SubmittingPatches`\n> +- `Documentation/MyFirstContribution.txt`\n> +\n> +[[proper-use-of-to-and-cc]]\n> +== Proper Use of To and Cc\n> +\n> +The \"To:\" field is the place to list the people you want to directly interact\n> +with and request responses from and the \"Cc:\" field is for other people that\n> +you wish to inform of this conversation. Everybody is welcome to chime in on\n> +the thread. When there is no particular person you wish to talk to, the mailing\n> +list address is a good catch-all addres to reach everybody and should be put in\n> +the \"To:\" field.\n> +\n> +When replying to an email on the mailing list, put the person you are replying\n> +to in the \"To:\" field and all other people in the thread in the \"Cc:\" field,\n> +including the mailing list address.\n> +\n> +The motivation for the above suggestions is to allow recipients to prioritize\n> +their incoming messages; they can direct their immediate attention to those\n> +messages with their names on the \"To:\" field and the ones with their names on\n> +the \"Cc:\" field can wait.\n> +\n> +Make sure to keep everyone involved in the \"Cc:\" field so that they do not have\n> +to be subscribed to the mailing list to receive replies.\n> +\n> +[[proper-use-of-subject]]\n> +== Proper Use of the Subject\n> +\n> +When replying to an email on the list, make sure that the subject of the\n> +original email is the subject of your email with \"Re:\" added to it. So if\n> +you reply to an email with subject \"first post\", the subject of your email\n> +should be \"Re: first post\".\n> +\n> +Sometimes email threads diverge into other threads about related, but distinct\n> +topics. In those cases, the subject like should change to the new topic and\n> +include in parenthesis \"(Was: )\". So for instance,\n> +if a side thread is created from the \"first post\" thread example, the subject\n> +line should be something like \"second post (was: first post)\" with replies\n> +having the subject \"Re: second post (was: first post)\".\n> +\n> +[[use-interleaved-style]]\n> +== Use Interleaved Style in Replies\n> +\n> +> A: Because it messes up the order in which people normally read text.\n> +> Q: Why is top-posting such a bad thing?\n> +> A: Top-posting.\n> +> Q: What is the most annoying thing in email?\n> +\n> +When replying to emails, use interleaved style which is also sometimes called\n> +an \"inline reply\". This creates a natural flow for the reader of the reply. They\n> +can easily see what the context for the reply is. Also leave only the context\n> +that is important for your reply and delete the rest.\n> +\n> +[[do-not-use-mail-followup-to]]\n> +== Do Not Use Mail-Followup-To\n> +\n> +When posting to the mailing list, your email client might add a\n> +\"Mail-Followup-To:\" field containing all of the recipients, including the\n> +mailing list address, but not the sender's email address. This is intended to\n> +prevent the sender from receiving replies twice, once from the replying person\n> +and again from the mailing list.\n> +\n> +This goes directly against the desired \"To:\" and \"Cc:\" etiquette (see \"Proper\n> +Use of To and Cc\" above) because \"Reply to all\"/\"group reply\" will redirect the\n> +response to all of the people in the original \"Cc:\" field instead of going to\n> +the person who sent the message being responded to.\n> +\n> +Some email clients, such as Mutt (see Disable Mail-Followup-To in the Mutt\n> +section below) are configured by default to add \"Mail-Followup-To:\" fields and\n> +to honor existing \"Mail-Followup-To:\" fields. It is best to disable both.\n> +\n> +[[enable-plain-text-mode]]\n> +== Enable Plain Text Mode\n> +\n> +The Git mailing list software rejects email sent in text/html format. It is\n> +important that your email client is set to create text/plain emails to ensure\n> +delivery.\n> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\n> index 55287d72e0..4f8b9f24ee 100644\n> --- a/Documentation/SubmittingPatches\n> +++ b/Documentation/SubmittingPatches\n> @@ -433,7 +433,7 @@ help you find out who they are.\n> \n> In any time between the (2)-(3) cycle, the maintainer may pick it up\n> from the list and queue it to `seen`, in order to make it easier for\n> -people play with it without having to pick up and apply the patch to\n> +people to play with it without having to pick up and apply the patch to\n> their trees themselves.\n> \n> [[patch-status]]\n> @@ -450,6 +450,46 @@ their trees themselves.\n> entitled \"What's cooking in git.git\" and \"What's in git.git\" giving\n> the status of various proposed changes.\n> \n> +[[patches-that-receive-no-response]]\n> +== Patches that Receive No Response\n> +\n> +If you sent a patch and you did not hear any response from anybody for\n> +several days, it could be that your patch was totally uninteresting,\n> +but it also is possible that it was simply lost in the noise. Please\n> +do not hesitate to send a reminder message in such a case. Messages\n> +getting lost in the noise may be a sign that those who can evaluate\n> +your patch don't have enough mental/time bandwidth to process them\n> +right at the moment, and it often helps to wait until the list traffic\n> +becomes calmer before sending such a reminder.\n> +\n> +Alternatives to sending direct reminders are:\n> +\n> +* Wait for the next \"What's cooking in git.git\" email to see if your patch\n> + series was mentioned and replying to that email with a note pointing out that\n> + your patch series has been overlooked.\n> +\n> +* Attend the weekly \"stand-up\" meeting held in the \"#git-devel\" channel on\n> + irc.freenode.net and bring it up then.\n> +\n> +[[send-merge-ready-patches-to-the-maintainer]]\n> +== Send Merge-Ready Patches to the Maintainer\n> +\n> +Once a patch has achieved consensus and all stakeholders are satisfied and\n> +everything is ready for merging, you have two main options for getting your\n> +patch noticed by the maintainer.\n> +\n> +1. Submit a new, final, version of the patch with an accurate list of commit\n> + trailers. Make this submission \"To:\" the maintainer, \"In-Reply-To:\" the\n> + previous version of the patch, and add everybody concerned, including the\n> + mailing list address to the \"Cc:\" field. This is a nice way to reduce the\n> + amount of work the maintainer must do to merge the patch while also getting\n> + their attention.\n> +\n> +2. Creating a \"group reply\"/\"Reply to all\" email to the latest patch series\n> + with the maintainer in the \"To:\" field. This is sometimes referred to as a\n> + \"review ping\" email and is appropriate if the patch requires no more work\n> + and is in its final state with an accurate list of commit trailers.\n> +\n> [[travis]]\n> == GitHub-Travis CI hints\n> \n> @@ -510,6 +550,38 @@ first patch.\\n\", if you really want to put in the patch e-mail,\n> should come after the three-dash line that signals the end of the\n> commit message.\n> \n> +=== Mutt\n> +\n> +[[known-mailing-lists]]\n> +==== Known Mailing Lists\n> +\n> +Mutt has the ability to change its behavior when replying to a mailing list. You\n> +must specify mailing list addresses using the `subscribe` keyword in your Mutt\n> +configuration:\n> +\n> +**~/.muttrc:**\n> +```\n> +# tell Mutt about the Git mailing list\n> +subscribe git@vger.kernel.org\n> +```\n> +\n> +[[disable-mail-followup-to]]\n> +==== Disable Mail-Followup-To\n> +\n> +By default, when replying to mailing lists, Mutt automatically generates\n> +\"Mail-Followup-To:\" fields. To fix this, disable the generation of the field\n> +in your Mutt configuration. It is also a good idea to disable honoring any\n> +\"Mail-Followup-To:\" field so that your \"group reply\" operations are correctly\n> +addressed.\n> +\n> +**~/.muttrc:**\n> +```\n> +# disable Mail-Followup-To header\n> +unset followup_to\n> +\n> +# disable honoring Mail-Followup-To header\n> +unset honor_followup_to\n> +```\n> \n> === Pine\n"},{"id":"424414","messageId":"d3c48e85-e8ac-60aa-0588-4ff891d38dbd@gmail.com","threadId":"55667","inReplyTo":"20210512233412.10737-1-dwh@linuxprogrammer.org","subject":"Re: [PATCH v3] doc: writing down Git mailing list etiquette","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-05-13T04:06:03Z","receivedAt":"2021-05-13T04:06:13Z","isPatch":true,"sender":{"key":"bagasdotme@gmail.com","avatar":"https://avatars.githubusercontent.com/u/40219486?v=4"},"body":"On 13/05/21 06.34, Dave Huseby wrote:\n> After violating a few unspoken etiquette rules while submitting patches\n> to the Git mailing list, it was suggeted that somebody write a guide.\n> Since I was the latest cause of this perenial discussion, I took it upon\n> myself to learn from my mistakes and document the Git mailing list\n> etiquette and the fixes I made to my email setup.\n> \n\nThe commit message looks too personal here. Anyways, better say:\n\n```\nDevelopers who are new to Git mailing list may not feel that they\nviolated unspoken etiquette rules in the list until someone point\nout the discussions about such rules.\n\nTo avoid such perennial discussions, document the etiquette rules\napplied to Git mailing list. Also add sections about submitting\nfinal (merge-ready) patch, actions when a patch receives no\nresponse, and hints for Mutt to Documentation/SubmittingPatches.\n```\n\nBut anyway for SubmittingPatches changes, I think it's better\nto send it as separate patch.\n\n> * Add documentation specifically on Git mailing list etiquette\n> * Add alternative actions for patches that receive no response.\n> * Add section on submitting a final, merge-ready patch.\n> * Add section on Mutt MUA settings.\n> \n> Reported-by: Christian Couder \n> Reported-by: Filipe Contreras \n> Thanks-to: Junio C Hamano \n> Thanks-to: Philip Oakley \n> Thanks-to: Bagas Sanjaya \n> Thanks-to: Eric Sunshine \n> Thanks-to: Ævar Arnfjörð Bjarmason \n> Signed-off-by: Dave Huseby \n> ---\n> Documentation/MailingListEtiquette.txt | 93 ++++++++++++++++++++++++++\n> Documentation/SubmittingPatches | 74 +++++++++++++++++++-\n> 2 files changed, 166 insertions(+), 1 deletion(-)\n> create mode 100644 Documentation/MailingListEtiquette.txt\n> \n> diff --git a/Documentation/MailingListEtiquette.txt b/Documentation/MailingListEtiquette.txt\n> new file mode 100644\n> index 0000000000..8a383f81a8\n> --- /dev/null\n> +++ b/Documentation/MailingListEtiquette.txt\n> @@ -0,0 +1,93 @@\n> +Mailing List Etiquette\n> +======================\n> +\n> +[[introduction]]\n> +== Introduction\n> +\n> +The Git project uses a mailing list and email to coordinate development and\n> +submit patches. Many other open source projects use web-based forums and pull\n> +requests (PRs) to achieve the same thing. This article focuses entirely on the\n> +Git project and the etiquette and unspoken rules that have developed over the\n> +years. What follows are best practices and suggestions for the \"proper\" way to\n> +interact via email on the Git mailing list.\n> +\n> +If you are looking for details on how to submit a patch, that is documented\n> +elsewhere in:\n> +\n> +- `Documentation/SubmittingPatches`\n> +- `Documentation/MyFirstContribution.txt`\n> +\n> +[[proper-use-of-to-and-cc]]\n> +== Proper Use of To and Cc\n> +\n> +The \"To:\" field is the place to list the people you want to directly interact\n> +with and request responses from and the \"Cc:\" field is for other people that\n> +you wish to inform of this conversation. Everybody is welcome to chime in on\n> +the thread. When there is no particular person you wish to talk to, the mailing\n> +list address is a good catch-all addres to reach everybody and should be put in\n> +the \"To:\" field.\n> +\n> +When replying to an email on the mailing list, put the person you are replying\n> +to in the \"To:\" field and all other people in the thread in the \"Cc:\" field,\n> +including the mailing list address.\n> +\n> +The motivation for the above suggestions is to allow recipients to prioritize\n> +their incoming messages; they can direct their immediate attention to those\n> +messages with their names on the \"To:\" field and the ones with their names on\n> +the \"Cc:\" field can wait.\n> +\n> +Make sure to keep everyone involved in the \"Cc:\" field so that they do not have\n> +to be subscribed to the mailing list to receive replies.\n> +\n> +[[proper-use-of-subject]]\n> +== Proper Use of the Subject\n> +\n> +When replying to an email on the list, make sure that the subject of the\n> +original email is the subject of your email with \"Re:\" added to it. So if\n> +you reply to an email with subject \"first post\", the subject of your email\n> +should be \"Re: first post\".\n> +\n> +Sometimes email threads diverge into other threads about related, but distinct\n> +topics. In those cases, the subject like should change to the new topic and\n> +include in parenthesis \"(Was: )\". So for instance,\n> +if a side thread is created from the \"first post\" thread example, the subject\n> +line should be something like \"second post (was: first post)\" with replies\n> +having the subject \"Re: second post (was: first post)\".\n> +\n> +[[use-interleaved-style]]\n> +== Use Interleaved Style in Replies\n> +\n> +> A: Because it messes up the order in which people normally read text.\n> +> Q: Why is top-posting such a bad thing?\n> +> A: Top-posting.\n> +> Q: What is the most annoying thing in email?\n> +\n\nWhen you describe about interleaved style below, you also include example of\n\"top posting\". This make newbies think that TP (like above) is interleaved\nstyle, while both are actually different. So please also include example of\ninterleaved style.\n\n> +When replying to emails, use interleaved style which is also sometimes called\n> +an \"inline reply\". This creates a natural flow for the reader of the reply. They\n> +can easily see what the context for the reply is. Also leave only the context\n> +that is important for your reply and delete the rest.\n> +\n> +[[do-not-use-mail-followup-to]]\n> +== Do Not Use Mail-Followup-To\n> +\n> +When posting to the mailing list, your email client might add a\n> +\"Mail-Followup-To:\" field containing all of the recipients, including the\n> +mailing list address, but not the sender's email address. This is intended to\n> +prevent the sender from receiving replies twice, once from the replying person\n> +and again from the mailing list.\n> +\n> +This goes directly against the desired \"To:\" and \"Cc:\" etiquette (see \"Proper\n> +Use of To and Cc\" above) because \"Reply to all\"/\"group reply\" will redirect the\n> +response to all of the people in the original \"Cc:\" field instead of going to\n> +the person who sent the message being responded to.\n> +\n> +Some email clients, such as Mutt (see Disable Mail-Followup-To in the Mutt\n> +section below) are configured by default to add \"Mail-Followup-To:\" fields and\n> +to honor existing \"Mail-Followup-To:\" fields. It is best to disable both.\n> +\n\nThe specific hints for Mutt is on Documentation/SubmittingPatches, included as\npart of this patch, not on Documentation/MailingListEtiquette.txt that you\nwrote.\n\n> +[[enable-plain-text-mode]]\n> +== Enable Plain Text Mode\n> +\n> +The Git mailing list software rejects email sent in text/html format. It is\n> +important that your email client is set to create text/plain emails to ensure\n> +delivery.\n\nDon't you know that VGER (that hosts Git ML) rejects text/html emails because\nthese are very likely spam messages?\n\n> +[[send-merge-ready-patches-to-the-maintainer]]\n> +== Send Merge-Ready Patches to the Maintainer\n> +\n> +Once a patch has achieved consensus and all stakeholders are satisfied and\n> +everything is ready for merging, you have two main options for getting your\n> +patch noticed by the maintainer.\n> +\n> +1. Submit a new, final, version of the patch with an accurate list of commit\n> + trailers. Make this submission \"To:\" the maintainer, \"In-Reply-To:\" the\n> + previous version of the patch, and add everybody concerned, including the\n> + mailing list address to the \"Cc:\" field. This is a nice way to reduce the\n> + amount of work the maintainer must do to merge the patch while also getting\n> + their attention.\n> +\n> +2. Creating a \"group reply\"/\"Reply to all\" email to the latest patch series\n> + with the maintainer in the \"To:\" field. This is sometimes referred to as a\n> + \"review ping\" email and is appropriate if the patch requires no more work\n> + and is in its final state with an accurate list of commit trailers.\n> +\n\nFor this section, I expect that the paragraph that started with \"After the list\nreached a consensus that it is a good idea to apply the patch, re-send it with\n\"To:\"...\" be also deleted to avoid redundancy.\n\n> [[travis]]\n> == GitHub-Travis CI hints\n> \n> @@ -510,6 +550,38 @@ first patch.\\n\", if you really want to put in the patch e-mail,\n> should come after the three-dash line that signals the end of the\n> commit message.\n> \n> +=== Mutt\n> +\n> +[[known-mailing-lists]]\n> +==== Known Mailing Lists\n> +\n> +Mutt has the ability to change its behavior when replying to a mailing list. You\n> +must specify mailing list addresses using the `subscribe` keyword in your Mutt\n> +configuration:\n> +\n> +**~/.muttrc:**\n> +```\n> +# tell Mutt about the Git mailing list\n> +subscribe git@vger.kernel.org\n> +```\n> +\n> +[[disable-mail-followup-to]]\n> +==== Disable Mail-Followup-To\n> +\n> +By default, when replying to mailing lists, Mutt automatically generates\n> +\"Mail-Followup-To:\" fields. To fix this, disable the generation of the field\n> +in your Mutt configuration. It is also a good idea to disable honoring any\n> +\"Mail-Followup-To:\" field so that your \"group reply\" operations are correctly\n> +addressed.\n> +\n> +**~/.muttrc:**\n> +```\n> +# disable Mail-Followup-To header\n> +unset followup_to\n> +\n> +# disable honoring Mail-Followup-To header\n> +unset honor_followup_to\n> +```\n> \n> === Pine\n> \n> \n From the context hunk for this Mutt subsection, I was thought that it was inside\n\"Travis hints\" sub/section, but after seeing \"Pine\" subsection below the addition,\nI recognized that subsection for Mutt was in \"MUA specific\" section.\n\nThanks.\n\n-- \nAn old man doll... just what I always wanted! - Clara\n"},{"id":"424424","messageId":"609cc88947e4a_329320899@natae.notmuch","threadId":"55667","inReplyTo":"20210512233412.10737-1-dwh@linuxprogrammer.org","subject":"RE: [PATCH v3] doc: writing down Git mailing list etiquette","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-13T06:34:49Z","receivedAt":"2021-05-13T06:34:58Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Dave Huseby wrote:\n> +[[proper-use-of-to-and-cc]]\n> +== Proper Use of To and Cc\n\nAlways make sure the mailing list is included.\n\n...\n\n> +[[proper-use-of-subject]]\n> +== Proper Use of the Subject\n\n...\n\nI think this is more importan than the point above.\n\n> +[[use-interleaved-style]]\n> +== Use Interleaved Style in Replies\n> +\n> +> A: Because it messes up the order in which people normally read text.\n> +> Q: Why is top-posting such a bad thing?\n> +> A: Top-posting.\n> +> Q: What is the most annoying thing in email?\n\nYou need to explain this is top-posting, and it's an example of what not\nto do.\n\n...\n\n> +[[do-not-use-mail-followup-to]]\n> +== Do Not Use Mail-Followup-To\n\n...\n\nThis should be the last point.\n\n> +[[enable-plain-text-mode]]\n> +== Enable Plain Text Mode\n> +\n> +The Git mailing list software rejects email sent in text/html format. It is\n> +important that your email client is set to create text/plain emails to ensure\n> +delivery.\n\nThis is more important than other points.\n\nIMO the order should be:\n\n 1. Enable plain-text mode\n 2. Proper use of subject\n 3. Use interleaved-style\n 4. Proper use of To/Cc\n 5. Do not use mail-followup-to\n\n> --- a/Documentation/SubmittingPatches\n> +++ b/Documentation/SubmittingPatches\n> @@ -433,7 +433,7 @@ help you find out who they are.\n\n...\n\n> +[[patches-that-receive-no-response]]\n> +== Patches that Receive No Response\n\nI would put this in a separate patch.\n\nCheers.\n\n-- \nFelipe Contreras\n"},{"id":"424430","messageId":"d40d84f6-52b1-af46-859f-80e4b15f4db6@gmail.com","threadId":"55667","inReplyTo":"20210512233412.10737-1-dwh@linuxprogrammer.org","subject":"Re: [PATCH v3] doc: writing down Git mailing list etiquette","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-05-13T07:01:25Z","receivedAt":"2021-05-13T07:01:46Z","isPatch":true,"sender":{"key":"bagasdotme@gmail.com","avatar":"https://avatars.githubusercontent.com/u/40219486?v=4"},"body":"Another review.\n\nOn 13/05/21 06.34, Dave Huseby wrote:\n> After violating a few unspoken etiquette rules while submitting patches\n> to the Git mailing list, it was suggeted that somebody write a guide.\n> Since I was the latest cause of this perenial discussion, I took it upon\n> myself to learn from my mistakes and document the Git mailing list\n> etiquette and the fixes I made to my email setup.\n> \n> * Add documentation specifically on Git mailing list etiquette\n> * Add alternative actions for patches that receive no response.\n> * Add section on submitting a final, merge-ready patch.\n> * Add section on Mutt MUA settings.\n> \n> Reported-by: Christian Couder \n> Reported-by: Filipe Contreras \n> Thanks-to: Junio C Hamano \n> Thanks-to: Philip Oakley \n> Thanks-to: Bagas Sanjaya \n> Thanks-to: Eric Sunshine \n> Thanks-to: Ævar Arnfjörð Bjarmason \n> Signed-off-by: Dave Huseby \n> ---\n> Documentation/MailingListEtiquette.txt | 93 ++++++++++++++++++++++++++\n> Documentation/SubmittingPatches | 74 +++++++++++++++++++-\n> 2 files changed, 166 insertions(+), 1 deletion(-)\n> create mode 100644 Documentation/MailingListEtiquette.txt\n> \n> diff --git a/Documentation/MailingListEtiquette.txt b/Documentation/MailingListEtiquette.txt\n> new file mode 100644\n> index 0000000000..8a383f81a8\n> --- /dev/null\n> +++ b/Documentation/MailingListEtiquette.txt\n> @@ -0,0 +1,93 @@\n> +Mailing List Etiquette\n> +======================\n> +\n> +[[introduction]]\n> +== Introduction\n> +\n> +The Git project uses a mailing list and email to coordinate development and\n> +submit patches. Many other open source projects use web-based forums and pull\n> +requests (PRs) to achieve the same thing. This article focuses entirely on the\n> +Git project and the etiquette and unspoken rules that have developed over the\n> +years. What follows are best practices and suggestions for the \"proper\" way to\n> +interact via email on the Git mailing list.\n> +\n> +If you are looking for details on how to submit a patch, that is documented\n> +elsewhere in:\n> +\n> +- `Documentation/SubmittingPatches`\n> +- `Documentation/MyFirstContribution.txt`\n> +\n> +[[proper-use-of-to-and-cc]]\n> +== Proper Use of To and Cc\n> +\n> +The \"To:\" field is the place to list the people you want to directly interact\n> +with and request responses from and the \"Cc:\" field is for other people that\n> +you wish to inform of this conversation. Everybody is welcome to chime in on\n> +the thread. When there is no particular person you wish to talk to, the mailing\n> +list address is a good catch-all addres to reach everybody and should be put in\n> +the \"To:\" field.\n> +\n> +When replying to an email on the mailing list, put the person you are replying\n> +to in the \"To:\" field and all other people in the thread in the \"Cc:\" field,\n> +including the mailing list address.\n> +\n> +The motivation for the above suggestions is to allow recipients to prioritize\n> +their incoming messages; they can direct their immediate attention to those\n> +messages with their names on the \"To:\" field and the ones with their names on\n> +the \"Cc:\" field can wait.\n> +\n> +Make sure to keep everyone involved in the \"Cc:\" field so that they do not have\n> +to be subscribed to the mailing list to receive replies.\n> +\n> +[[proper-use-of-subject]]\n> +== Proper Use of the Subject\n> +\n> +When replying to an email on the list, make sure that the subject of the\n> +original email is the subject of your email with \"Re:\" added to it. So if\n> +you reply to an email with subject \"first post\", the subject of your email\n> +should be \"Re: first post\".\n> +\n> +Sometimes email threads diverge into other threads about related, but distinct\n> +topics. In those cases, the subject like should change to the new topic and\n> +include in parenthesis \"(Was: )\". So for instance,\n> +if a side thread is created from the \"first post\" thread example, the subject\n> +line should be something like \"second post (was: first post)\" with replies\n> +having the subject \"Re: second post (was: first post)\".\n> +\n> +[[use-interleaved-style]]\n> +== Use Interleaved Style in Replies\n> +\n> +> A: Because it messes up the order in which people normally read text.\n> +> Q: Why is top-posting such a bad thing?\n> +> A: Top-posting.\n> +> Q: What is the most annoying thing in email?\n> +\n> +When replying to emails, use interleaved style which is also sometimes called\n> +an \"inline reply\". This creates a natural flow for the reader of the reply. They\n> +can easily see what the context for the reply is. Also leave only the context\n> +that is important for your reply and delete the rest.\n> +\n> +[[do-not-use-mail-followup-to]]\n> +== Do Not Use Mail-Followup-To\n> +\n> +When posting to the mailing list, your email client might add a\n> +\"Mail-Followup-To:\" field containing all of the recipients, including the\n> +mailing list address, but not the sender's email address. This is intended to\n> +prevent the sender from receiving replies twice, once from the replying person\n> +and again from the mailing list.\n> +\n> +This goes directly against the desired \"To:\" and \"Cc:\" etiquette (see \"Proper\n> +Use of To and Cc\" above) because \"Reply to all\"/\"group reply\" will redirect the\n> +response to all of the people in the original \"Cc:\" field instead of going to\n> +the person who sent the message being responded to.\n> +\n> +Some email clients, such as Mutt (see Disable Mail-Followup-To in the Mutt\n> +section below) are configured by default to add \"Mail-Followup-To:\" fields and\n> +to honor existing \"Mail-Followup-To:\" fields. It is best to disable both.\n> +\n> +[[enable-plain-text-mode]]\n> +== Enable Plain Text Mode\n> +\n> +The Git mailing list software rejects email sent in text/html format. It is\n> +important that your email client is set to create text/plain emails to ensure\n> +delivery.\n> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\n> index 55287d72e0..4f8b9f24ee 100644\n> --- a/Documentation/SubmittingPatches\n> +++ b/Documentation/SubmittingPatches\n> @@ -433,7 +433,7 @@ help you find out who they are.\n> \n> In any time between the (2)-(3) cycle, the maintainer may pick it up\n> from the list and queue it to `seen`, in order to make it easier for\n> -people play with it without having to pick up and apply the patch to\n> +people to play with it without having to pick up and apply the patch to\n> their trees themselves.\n> \n> [[patch-status]]\n> @@ -450,6 +450,46 @@ their trees themselves.\n> entitled \"What's cooking in git.git\" and \"What's in git.git\" giving\n> the status of various proposed changes.\n> \n> +[[patches-that-receive-no-response]]\n> +== Patches that Receive No Response\n> +\n> +If you sent a patch and you did not hear any response from anybody for\n> +several days, it could be that your patch was totally uninteresting,\n> +but it also is possible that it was simply lost in the noise. Please\n> +do not hesitate to send a reminder message in such a case. Messages\n> +getting lost in the noise may be a sign that those who can evaluate\n> +your patch don't have enough mental/time bandwidth to process them\n> +right at the moment, and it often helps to wait until the list traffic\n> +becomes calmer before sending such a reminder.\n> +\n> +Alternatives to sending direct reminders are:\n> +\n> +* Wait for the next \"What's cooking in git.git\" email to see if your patch\n> + series was mentioned and replying to that email with a note pointing out that\n> + your patch series has been overlooked.\n> +\n> +* Attend the weekly \"stand-up\" meeting held in the \"#git-devel\" channel on\n> + irc.freenode.net and bring it up then.\n> +\n> +[[send-merge-ready-patches-to-the-maintainer]]\n> +== Send Merge-Ready Patches to the Maintainer\n> +\n> +Once a patch has achieved consensus and all stakeholders are satisfied and\n> +everything is ready for merging, you have two main options for getting your\n> +patch noticed by the maintainer.\n> +\n> +1. Submit a new, final, version of the patch with an accurate list of commit\n> + trailers. Make this submission \"To:\" the maintainer, \"In-Reply-To:\" the\n> + previous version of the patch, and add everybody concerned, including the\n> + mailing list address to the \"Cc:\" field. This is a nice way to reduce the\n> + amount of work the maintainer must do to merge the patch while also getting\n> + their attention.\n> +\n> +2. Creating a \"group reply\"/\"Reply to all\" email to the latest patch series\n> + with the maintainer in the \"To:\" field. This is sometimes referred to as a\n> + \"review ping\" email and is appropriate if the patch requires no more work\n> + and is in its final state with an accurate list of commit trailers.\n> +\n> [[travis]]\n> == GitHub-Travis CI hints\n> \n> @@ -510,6 +550,38 @@ first patch.\\n\", if you really want to put in the patch e-mail,\n> should come after the three-dash line that signals the end of the\n> commit message.\n> \n> +=== Mutt\n> +\n> +[[known-mailing-lists]]\n> +==== Known Mailing Lists\n> +\n> +Mutt has the ability to change its behavior when replying to a mailing list. You\n> +must specify mailing list addresses using the `subscribe` keyword in your Mutt\n> +configuration:\n> +\n> +**~/.muttrc:**\n> +```\n> +# tell Mutt about the Git mailing list\n> +subscribe git@vger.kernel.org\n> +```\n> +\n> +[[disable-mail-followup-to]]\n> +==== Disable Mail-Followup-To\n> +\n> +By default, when replying to mailing lists, Mutt automatically generates\n> +\"Mail-Followup-To:\" fields. To fix this, disable the generation of the field\n> +in your Mutt configuration. It is also a good idea to disable honoring any\n> +\"Mail-Followup-To:\" field so that your \"group reply\" operations are correctly\n> +addressed.\n> +\n> +**~/.muttrc:**\n> +```\n> +# disable Mail-Followup-To header\n> +unset followup_to\n> +\n> +# disable honoring Mail-Followup-To header\n> +unset honor_followup_to\n> +```\n> \n> === Pine\n> \n> \n\nI think the patch title, according to diff body, should be\n\"doc: document mailing list etiquette and various updates to SubmittingPatches\".\nBut anyway, it's better to split into two separate patches (one that document\netiquette and one that add updates to SubmittingPatches) because there are two\nlogical changes in single patch.\n\nRegarding patch title, I proposed change above because we require that the title\nuse imperative language (\"make something do one thing\"). However, you use\npresent continuous tense (with gerund \"-ing\"), which implied that you do\nsomething progressively (\"making something do one thing\"). This is not\nimperative language, just descriptive.\n\n-- \nAn old man doll... just what I always wanted! - Clara\n"},{"id":"424484","messageId":"20210513171706.GD11882@localhost","threadId":"55667","inReplyTo":"xmqqy2cjcwn4.fsf@gitster.g","subject":"Re: [PATCH v3] doc: writing down Git mailing list etiquette","fromName":"Dave Huseby","fromEmail":"dwh@linuxprogrammer.org","sentAt":"2021-05-13T17:17:06Z","receivedAt":"2021-05-13T17:17:19Z","isPatch":true,"sender":{"key":"dwh@linuxprogrammer.org","avatar":null},"body":"On 13.05.2021 09:20, Junio C Hamano wrote:\n>I've read this version over, and did not find much that is\n>objectionable, but as some others said on the previous round, there\n>may be overlaps and repetitions we'd rather get rid of. We should\n>be able to cover discussions around patches in the SubmittingPatches\n>document without introducing a new document, so all that remains is\n>what to do with non-patch discussions. I suspect that it might even\n>be sufficient to (1) taylor descriptions introduced in this patch\n>for discussions around patches and reviews, and add it as a new\n>section to SubmittingPatches and (2) mention that the same principle\n>applies to non-patch communication in the same section as a sidenote\n>but obviously others may disagree.\n\nI realized last night that there is an important distinction between\nusing email to work *with* Git and using email to work *on* Git. The Git\nML has its own etiquette and rules and MUA tweaks that may not apply to\nother projects that use Git and a mailing list. The files\nMyFirstContribution.txt and SubmittingPatches are clearly focused on\nusing email to work *on* Git. The file MyFirstObjectWalk.txt is also\nabout working *on* Git, although unrelated to email and the mailing\nlist. Maybe it's time we make the *on*/*with* distinction more obvious\nby creating a Documentation/WorkingOnGit subdir? Just throwing that out\nthere.\n\nIt sounds to me like adding a MailingListEtiquette.txt file isn't the\nfavored approach. I can tailor the information in here to fit into new\nsections of SubmittingPatches.\n\n>Ævar, you also have some updates to SubmittingPatches in flight.\n>\n>Can I ask you to work with Dave to figure out how well this update\n>fits in the entire picture as a stakeholder to the document (i.e.\n>not as \"the guilty party who is involved in conflicts\", but as\n>\"somebody who has been long enough to be qualified to guide the\n>evolution of the document, and obviously is interested in improving\n>the document\")?\n\nI saw Ævar's patches last night and had the same thought. Since it looks\nlike this is probably all going into SubmittingPatches, I'll connect\nwith Ævar and see if we can come up with a patch series for (1) Ævar's\nre-org and pruning (2) my Mutt MUA settings and (3) etiquette related\ninformation for discussions around patches and reviews with a (4) side\nnote for any general etiquette for non-patch communication.\n\nThoughts?\n\n>Thanks.\n\nNo, thank you. And thank you to Felipe and Bagas for such thorough\nreviews.\n\n"},{"id":"424499","messageId":"609d8645626ac_80a2208cc@natae.notmuch","threadId":"55667","inReplyTo":"20210513171706.GD11882@localhost","subject":"Re: [PATCH v3] doc: writing down Git mailing list etiquette","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-13T20:04:21Z","receivedAt":"2021-05-13T20:04:25Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Dave Huseby wrote:\n> It sounds to me like adding a MailingListEtiquette.txt file isn't the\n> favored approach. I can tailor the information in here to fit into new\n> sections of SubmittingPatches.\n\nI don't think this belongs to SubmittingPatches because it applies to\n*everyone*, yes people submitting patches, but also people reviewing\npatches. Additionally people submitting bug reports, people responding\nto bug reports. People suggesting improvements. And of course people\nmaintainging the project too.\n\nAlso, any other discussions.\n\n-- \nFelipe Contreras\n"},{"id":"424512","messageId":"xmqqk0o29w55.fsf@gitster.g","threadId":"55667","inReplyTo":"20210513171706.GD11882@localhost","subject":"Re: [PATCH v3] doc: writing down Git mailing list etiquette","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-05-13T21:11:34Z","receivedAt":"2021-05-13T21:11:43Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Dave Huseby writes:\n\n> I realized last night that there is an important distinction between\n> using email to work *with* Git and using email to work *on* Git. The Git\n> ML has its own etiquette and rules and MUA tweaks that may not apply to\n> other projects that use Git and a mailing list. The files\n> MyFirstContribution.txt and SubmittingPatches are clearly focused on\n> using email to work *on* Git. The file MyFirstObjectWalk.txt is also\n> about working *on* Git, although unrelated to email and the mailing\n> list. Maybe it's time we make the *on*/*with* distinction more obvious\n> by creating a Documentation/WorkingOnGit subdir? Just throwing that out\n> there.\n\nI agree with that \"realization\", and think we shouldn't talk\nanything about what other people who happens to use Git for their\nprojects should do, at least for now, when we do not even have a\ncompleted written guideline for ourselves to follow when using Git\nfor our projects.\n\n> I saw Ævar's patches last night and had the same thought. Since it looks\n> like this is probably all going into SubmittingPatches, I'll connect\n> with Ævar and see if we can come up with a patch series for (1) Ævar's\n> re-org and pruning (2) my Mutt MUA settings and (3) etiquette related\n> information for discussions around patches and reviews with a (4) side\n> note for any general etiquette for non-patch communication.\n\nSounds good. Thanks.\n"},{"id":"426909","messageId":"60c0fc311144f_1096b2081f@natae.notmuch","threadId":"55667","inReplyTo":"20210512233412.10737-1-dwh@linuxprogrammer.org","subject":"RE: [PATCH v3] doc: writing down Git mailing list etiquette","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-06-09T17:36:49Z","receivedAt":"2021-06-09T17:38:01Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Dave Huseby wrote:\n> After violating a few unspoken etiquette rules while submitting patches\n> to the Git mailing list, it was suggeted that somebody write a guide.\n> Since I was the latest cause of this perenial discussion, I took it upon\n> myself to learn from my mistakes and document the Git mailing list\n> etiquette and the fixes I made to my email setup.\n> \n> * Add documentation specifically on Git mailing list etiquette\n> * Add alternative actions for patches that receive no response.\n> * Add section on submitting a final, merge-ready patch.\n> * Add section on Mutt MUA settings.\n> \n> Reported-by: Christian Couder \n> Reported-by: Filipe Contreras \n> Thanks-to: Junio C Hamano \n> Thanks-to: Philip Oakley \n> Thanks-to: Bagas Sanjaya \n> Thanks-to: Eric Sunshine \n> Thanks-to: Ævar Arnfjörð Bjarmason \n> Signed-off-by: Dave Huseby \n\nWhat happened to this? I see value in having this document, so I would\nbe glad to pick it up if you've lost interest.\n\nCheers.\n\n-- \nFelipe Contreras"},{"id":"427903","messageId":"20210618204348.GA3763@localhost","threadId":"55667","inReplyTo":"60c0fc311144f_1096b2081f@natae.notmuch","subject":"Re: [PATCH v3] doc: writing down Git mailing list etiquette","fromName":"Dave Huseby","fromEmail":"dwh@linuxprogrammer.org","sentAt":"2021-06-18T20:43:48Z","receivedAt":"2021-06-18T20:43:52Z","isPatch":true,"sender":{"key":"dwh@linuxprogrammer.org","avatar":null},"body":"On 09.06.2021 12:36, Felipe Contreras wrote:\n>What happened to this? I see value in having this document, so I would\n>be glad to pick it up if you've lost interest.\n\nI fell off of the face of the earth. My life turned upside down but it's\nslowly righting itself. A number of things took me offline but the last\nof which is my father nearing the end of his life. Things are stable for\nthe moment so I am getting back in the saddle. Like I said in my last\nupdate, I'm going to try to combine all of the contributions and\nfeedback into a patchset that includes Ævar's patches and cleaned up\nversions of mine on top.\n\nRight now I'm trying to get my head back where it was.\n\nCheers!\nDave\n"},{"id":"427924","messageId":"60cd30c487a12_ca73a2084f@natae.notmuch","threadId":"55667","inReplyTo":"20210618204348.GA3763@localhost","subject":"Re: [PATCH v3] doc: writing down Git mailing list etiquette","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-06-18T23:48:20Z","receivedAt":"2021-06-18T23:48:30Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Dave Huseby wrote:\n> On 09.06.2021 12:36, Felipe Contreras wrote:\n> >What happened to this? I see value in having this document, so I would\n> >be glad to pick it up if you've lost interest.\n> \n> I fell off of the face of the earth. My life turned upside down but it's\n> slowly righting itself. A number of things took me offline but the last\n> of which is my father nearing the end of his life. Things are stable for\n> the moment so I am getting back in the saddle. Like I said in my last\n> update, I'm going to try to combine all of the contributions and\n> feedback into a patchset that includes Ævar's patches and cleaned up\n> versions of mine on top.\n> \n> Right now I'm trying to get my head back where it was.\n\nSorry to hear that. Hopefully soon you'll find some familiar ground.\n\nCheers.\n\n-- \nFelipe Contreras"}]}