{"thread":{"id":"47134","subject":"[PATCH] doc/SubmittingPatches: correct subject guidance","startedAt":"2017-11-08T13:17:13Z","lastAt":"2017-11-10T17:53:10Z","messageCount":8,"participants":["Adam Dinwoodie","Eric Sunshine","Josh Triplett"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"332071","messageId":"20171108131601.280992-1-adam@dinwoodie.org","threadId":"47134","inReplyTo":null,"subject":"[PATCH] doc/SubmittingPatches: correct subject guidance","fromName":"Adam Dinwoodie","fromEmail":"adam@dinwoodie.org","sentAt":"2017-11-08T13:16:01Z","receivedAt":"2017-11-08T13:17:13Z","isPatch":true,"sender":{"key":"adam@dinwoodie.org","avatar":"https://avatars.githubusercontent.com/u/1397507?v=4"},"body":"The examples and common practice for adding markers such as \"RFC\" or\n\"v2\" to the subject of patch emails is to have them within the same\nbrackets as the \"PATCH\" text. Update the description to match this\nbehaviour, rather than asserting such markers should be after the\nclosing bracket.\n\nSigned-off-by: Adam Dinwoodie \n---\n Documentation/SubmittingPatches | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex 558d465b6..e91ce8269 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -184,7 +184,7 @@ lose tabs that way if you are not careful.\n \n It is a common convention to prefix your subject line with\n [PATCH]. This lets people easily distinguish patches from other\n-e-mail discussions. Use of additional markers after PATCH and\n+e-mail discussions. Use of additional markers between PATCH and\n the closing bracket to mark the nature of the patch is also\n encouraged. E.g. [PATCH/RFC] is often used when the patch is\n not ready to be applied but it is for discussion, [PATCH v2],\n-- \n2.14.3\n\n"},{"id":"332073","messageId":"20171108134752.214056-1-adam@dinwoodie.org","threadId":"47134","inReplyTo":"20171108131601.280992-1-adam@dinwoodie.org","subject":"[PATCH v2] doc/SubmittingPatches: correct subject guidance","fromName":"Adam Dinwoodie","fromEmail":"adam@dinwoodie.org","sentAt":"2017-11-08T13:47:52Z","receivedAt":"2017-11-08T13:48:30Z","isPatch":true,"sender":{"key":"adam@dinwoodie.org","avatar":"https://avatars.githubusercontent.com/u/1397507?v=4"},"body":"The examples and common practice for adding markers such as \"RFC\" or\n\"v2\" to the subject of patch emails is to have them within the same\nbrackets as the \"PATCH\" text, not after the closing bracket. Further,\nthe practice of `git format-patch` and the like, as well as what appears\nto be the more common pratice on the mailing list, is to use \"[RFC\nPATCH]\", not \"[PATCH/RFC]\".\n\nUpdate the SubmittingPatches article to match.\n\nSigned-off-by: Adam Dinwoodie \n---\n\nI'm re-rolling this patch with some more substantive changes, as a bit\nmore research points to (a) \"RFC PATCH\" being more common on this\nmailing list than \"PATCH/RFC\", at least in recent usage, and (b) so the\ninstructions match the best practice according to `git format-patch` and\nfriends.\n\n Documentation/SubmittingPatches | 14 ++++++++------\n 1 file changed, 8 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex 558d465b6..95abf6084 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -184,12 +184,14 @@ lose tabs that way if you are not careful.\n \n It is a common convention to prefix your subject line with\n [PATCH]. This lets people easily distinguish patches from other\n-e-mail discussions. Use of additional markers after PATCH and\n-the closing bracket to mark the nature of the patch is also\n-encouraged. E.g. [PATCH/RFC] is often used when the patch is\n-not ready to be applied but it is for discussion, [PATCH v2],\n-[PATCH v3] etc. are often seen when you are sending an update to\n-what you have previously sent.\n+e-mail discussions. Use of markers in addition to PATCH within\n+the brackets to describe the nature of the patch is also\n+encouraged. E.g. [RFC PATCH] is often used when the patch is not\n+ready to be applied but it is for discussion, and can be added\n+with the `--rfc` argument to `git format-patch` or `git\n+send-email`, while [PATCH v2], [PATCH v3] etc. are often seen\n+when you are sending an update to what you have previously sent,\n+and can be added with the `-v ` arguments to the same commands.\n \n \"git format-patch\" command follows the best current practice to\n format the body of an e-mail message. At the beginning of the\n-- \n2.14.3\n\n"},{"id":"332075","messageId":"CAPig+cRaygrQ9_J1UHr_rynPsUn2J0--RHRvP2mFQbVQhWEm-Q@mail.gmail.com","threadId":"47134","inReplyTo":"20171108134752.214056-1-adam@dinwoodie.org","subject":"Re: [PATCH v2] doc/SubmittingPatches: correct subject guidance","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2017-11-08T14:10:27Z","receivedAt":"2017-11-08T14:10:33Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Wed, Nov 8, 2017 at 8:47 AM, Adam Dinwoodie wrote:\n> The examples and common practice for adding markers such as \"RFC\" or\n> \"v2\" to the subject of patch emails is to have them within the same\n> brackets as the \"PATCH\" text, not after the closing bracket. Further,\n> the practice of `git format-patch` and the like, as well as what appears\n> to be the more common pratice on the mailing list, is to use \"[RFC\n> PATCH]\", not \"[PATCH/RFC]\".\n>\n> Update the SubmittingPatches article to match.\n>\n> Signed-off-by: Adam Dinwoodie \n> ---\n> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\n> @@ -184,12 +184,14 @@ lose tabs that way if you are not careful.\n> It is a common convention to prefix your subject line with\n> [PATCH]. This lets people easily distinguish patches from other\n> -e-mail discussions. Use of additional markers after PATCH and\n> -the closing bracket to mark the nature of the patch is also\n> -encouraged. E.g. [PATCH/RFC] is often used when the patch is\n> -not ready to be applied but it is for discussion, [PATCH v2],\n> -[PATCH v3] etc. are often seen when you are sending an update to\n> -what you have previously sent.\n> +e-mail discussions. Use of markers in addition to PATCH within\n> +the brackets to describe the nature of the patch is also\n> +encouraged. E.g. [RFC PATCH] is often used when the patch is not\n> +ready to be applied but it is for discussion, and can be added\n> +with the `--rfc` argument to `git format-patch` or `git\n> +send-email`, while [PATCH v2], [PATCH v3] etc. are often seen\n\nIt has become a bit of a run-on sentence, but aside from that and the\nunnecessary extra whitespace between \"etc.\" and \"are\", it looks good\nto me.\n\n> +when you are sending an update to what you have previously sent,\n> +and can be added with the `-v ` arguments to the same commands.\n"},{"id":"332114","messageId":"20171109124714.GH20681@dinwoodie.org","threadId":"47134","inReplyTo":"CAPig+cRaygrQ9_J1UHr_rynPsUn2J0--RHRvP2mFQbVQhWEm-Q@mail.gmail.com","subject":"Re: [PATCH v2] doc/SubmittingPatches: correct subject guidance","fromName":"Adam Dinwoodie","fromEmail":"adam@dinwoodie.org","sentAt":"2017-11-09T12:47:14Z","receivedAt":"2017-11-09T12:47:22Z","isPatch":true,"sender":{"key":"adam@dinwoodie.org","avatar":"https://avatars.githubusercontent.com/u/1397507?v=4"},"body":"On Wednesday 08 November 2017 at 09:10 am -0500, Eric Sunshine wrote:\n> On Wed, Nov 8, 2017 at 8:47 AM, Adam Dinwoodie wrote:\n> > +e-mail discussions. Use of markers in addition to PATCH within\n> > +the brackets to describe the nature of the patch is also\n> > +encouraged. E.g. [RFC PATCH] is often used when the patch is not\n> > +ready to be applied but it is for discussion, and can be added\n> > +with the `--rfc` argument to `git format-patch` or `git\n> > +send-email`, while [PATCH v2], [PATCH v3] etc. are often seen\n> \n> It has become a bit of a run-on sentence, but aside from that and the\n> unnecessary extra whitespace between \"etc.\" and \"are\", it looks good\n> to me.\n\nBoth good points, thank you! I suspect the extra whitespace was a\nresult of Vim being \"helpful\" when reflowing the text.\n\nI'll re-spin now with fixed whitespace and breaking up the sentence a\nbit.\n"},{"id":"332115","messageId":"20171109130826.52132-1-adam@dinwoodie.org","threadId":"47134","inReplyTo":"20171109124714.GH20681@dinwoodie.org","subject":"[PATCH v3] doc/SubmittingPatches: correct subject guidance","fromName":"Adam Dinwoodie","fromEmail":"adam@dinwoodie.org","sentAt":"2017-11-09T13:08:26Z","receivedAt":"2017-11-09T13:09:09Z","isPatch":true,"sender":{"key":"adam@dinwoodie.org","avatar":"https://avatars.githubusercontent.com/u/1397507?v=4"},"body":"The examples and common practice for adding markers such as \"RFC\" or\n\"v2\" to the subject of patch emails is to have them within the same\nbrackets as the \"PATCH\" text, not after the closing bracket. Further,\nthe practice of `git format-patch` and the like, as well as what appears\nto be the more common pratice on the mailing list, is to use \"[RFC\nPATCH]\", not \"[PATCH/RFC]\".\n\nUpdate the SubmittingPatches article to match, and to reference the\n`format-patch` helper arguments.\n\nSigned-off-by: Adam Dinwoodie \nHelped-by: Eric Sunshine \n---\n Documentation/SubmittingPatches | 12 ++++++++----\n 1 file changed, 8 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex 558d465b6..ae59fd9d0 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -184,21 +184,25 @@ lose tabs that way if you are not careful.\n \n It is a common convention to prefix your subject line with\n [PATCH]. This lets people easily distinguish patches from other\n-e-mail discussions. Use of additional markers after PATCH and\n-the closing bracket to mark the nature of the patch is also\n-encouraged. E.g. [PATCH/RFC] is often used when the patch is\n+e-mail discussions. Use of markers in addition to PATCH within\n+the brackets to describe the nature of the patch is also\n+encouraged. E.g. [RFC PATCH] is often used when the patch is\n not ready to be applied but it is for discussion, [PATCH v2],\n [PATCH v3] etc. are often seen when you are sending an update to\n what you have previously sent.\n \n-\"git format-patch\" command follows the best current practice to\n+The \"git format-patch\" command follows the best current practice to\n format the body of an e-mail message. At the beginning of the\n patch should come your commit message, ending with the\n Signed-off-by: lines, and a line that consists of three dashes,\n followed by the diffstat information and the patch itself. If\n you are forwarding a patch from somebody else, optionally, at\n the beginning of the e-mail message just before the commit\n message starts, you can put a \"From: \" line to name that person.\n+To change the bracketed text at the start of the subject, use\n+`git format-patch --subject-prefix=`. As a shortcut, you\n+can use `--rfc` instead of `--subject-prefix=\"RFC PATCH\"`, or\n+`-v ` instead of `--subject-prefix=\"PATCH v\"`.\n \n You often want to add additional explanation about the patch,\n other than the commit message itself. Place such \"cover letter\"\n-- \n2.14.3\n\n"},{"id":"332124","messageId":"CAPig+cRADknKB7KxqcZVinwP9vmGh1tmUrySUND3hMTi7a+bag@mail.gmail.com","threadId":"47134","inReplyTo":"20171109130826.52132-1-adam@dinwoodie.org","subject":"Re: [PATCH v3] doc/SubmittingPatches: correct subject guidance","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2017-11-09T16:10:27Z","receivedAt":"2017-11-09T16:10:34Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Thu, Nov 9, 2017 at 8:08 AM, Adam Dinwoodie wrote:\n> The examples and common practice for adding markers such as \"RFC\" or\n> \"v2\" to the subject of patch emails is to have them within the same\n> brackets as the \"PATCH\" text, not after the closing bracket. Further,\n> the practice of `git format-patch` and the like, as well as what appears\n> to be the more common pratice on the mailing list, is to use \"[RFC\n> PATCH]\", not \"[PATCH/RFC]\".\n>\n> Update the SubmittingPatches article to match, and to reference the\n> `format-patch` helper arguments.\n>\n> Signed-off-by: Adam Dinwoodie \n> ---\n> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\n> @@ -184,21 +184,25 @@ lose tabs that way if you are not careful.\n> It is a common convention to prefix your subject line with\n> [PATCH]. This lets people easily distinguish patches from other\n> -e-mail discussions. Use of additional markers after PATCH and\n> -the closing bracket to mark the nature of the patch is also\n> -encouraged. E.g. [PATCH/RFC] is often used when the patch is\n> +e-mail discussions. Use of markers in addition to PATCH within\n> +the brackets to describe the nature of the patch is also\n> +encouraged. E.g. [RFC PATCH] is often used when the patch is\n> not ready to be applied but it is for discussion, [PATCH v2],\n\nNot a new problem, but since you're here cleaning this up, the \"not\nready to be applied but it is for discussion\" makes for a clunky read.\nPerhaps something roughly like:\n\n E.g. [RFC PATCH] is often used to indicate that a patch needs\n further discussion (\"request for comments\") before being\n accepted.\n\n> [PATCH v3] etc. are often seen when you are sending an update to\n> what you have previously sent.\n>\n> -\"git format-patch\" command follows the best current practice to\n> +The \"git format-patch\" command follows the best current practice to\n> format the body of an e-mail message. At the beginning of the\n> patch should come your commit message, ending with the\n> Signed-off-by: lines, and a line that consists of three dashes,\n> followed by the diffstat information and the patch itself. If\n> you are forwarding a patch from somebody else, optionally, at\n> the beginning of the e-mail message just before the commit\n> message starts, you can put a \"From: \" line to name that person.\n> +To change the bracketed text at the start of the subject, use\n> +`git format-patch --subject-prefix=`. As a shortcut, you\n\nThis may be nit-picky, but it took a bit of thought for me to work out\nwhat \"bracketed text at the start of the subject\" meant. I wonder if\nit would be clearer just to spell it out:\n\n To change the default \"[PATCH]\" in the subject to \"[]\", use\n `git format-patch --subject-prefix=`.\n\n> +can use `--rfc` instead of `--subject-prefix=\"RFC PATCH\"`, or\n> +`-v ` instead of `--subject-prefix=\"PATCH v\"`.\n\nOverall, this is much easier to digest than the run-on sentence in v2. Thanks.\n"},{"id":"332185","messageId":"20171110150250.8896-1-adam@dinwoodie.org","threadId":"47134","inReplyTo":"CAPig+cRADknKB7KxqcZVinwP9vmGh1tmUrySUND3hMTi7a+bag@mail.gmail.com","subject":"[PATCH v4] doc/SubmittingPatches: correct subject guidance","fromName":"Adam Dinwoodie","fromEmail":"adam@dinwoodie.org","sentAt":"2017-11-10T15:02:50Z","receivedAt":"2017-11-10T15:03:39Z","isPatch":true,"sender":{"key":"adam@dinwoodie.org","avatar":"https://avatars.githubusercontent.com/u/1397507?v=4"},"body":"The examples and common practice for adding markers such as \"RFC\" or\n\"v2\" to the subject of patch emails is to have them within the same\nbrackets as the \"PATCH\" text, not after the closing bracket. Further,\nthe practice of `git format-patch` and the like, as well as what appears\nto be the more common pratice on the mailing list, is to use \"[RFC\nPATCH]\", not \"[PATCH/RFC]\".\n\nUpdate the SubmittingPatches article to match and to reference the\n`format-patch` helper arguments, and also make some minor text\nclarifications in the area.\n\nSigned-off-by: Adam Dinwoodie \nHelped-by: Eric Sunshine \n---\n\nNotes:\n Changes since v3:\n - Clarified meaning of \"RFC\" per Eric's suggestion\n - Made the impact of --subject-prefix and friends clearer per Eric's\n suggestion\n \n Thank you for your nitpicking, Eric, it's useful and very much\n appreciated :)\n\n Documentation/SubmittingPatches | 19 ++++++++++++-------\n 1 file changed, 12 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex 558d465b6..89f239071 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -184,21 +184,26 @@ lose tabs that way if you are not careful.\n \n It is a common convention to prefix your subject line with\n [PATCH]. This lets people easily distinguish patches from other\n-e-mail discussions. Use of additional markers after PATCH and\n-the closing bracket to mark the nature of the patch is also\n-encouraged. E.g. [PATCH/RFC] is often used when the patch is\n-not ready to be applied but it is for discussion, [PATCH v2],\n-[PATCH v3] etc. are often seen when you are sending an update to\n-what you have previously sent.\n+e-mail discussions. Use of markers in addition to PATCH within\n+the brackets to describe the nature of the patch is also\n+encouraged. E.g. [RFC PATCH] (where RFC stands for \"request for\n+comments\") is often used to indicate a patch needs further\n+discussion before being accepted, [PATCH v2], [PATCH v3] etc.\n+are often seen when you are sending an update to what you have\n+previously sent.\n \n-\"git format-patch\" command follows the best current practice to\n+The \"git format-patch\" command follows the best current practice to\n format the body of an e-mail message. At the beginning of the\n patch should come your commit message, ending with the\n Signed-off-by: lines, and a line that consists of three dashes,\n followed by the diffstat information and the patch itself. If\n you are forwarding a patch from somebody else, optionally, at\n the beginning of the e-mail message just before the commit\n message starts, you can put a \"From: \" line to name that person.\n+To change the default \"[PATCH]\" in the subject to \"[]\", use\n+`git format-patch --subject-prefix=`. As a shortcut, you\n+can use `--rfc` instead of `--subject-prefix=\"RFC PATCH\"`, or\n+`-v ` instead of `--subject-prefix=\"PATCH v\"`.\n \n You often want to add additional explanation about the patch,\n other than the commit message itself. Place such \"cover letter\"\n-- \n2.14.3\n\n"},{"id":"332198","messageId":"20171110175257.elceafddaebm55uk@s","threadId":"47134","inReplyTo":"20171110150250.8896-1-adam@dinwoodie.org","subject":"Re: [PATCH v4] doc/SubmittingPatches: correct subject guidance","fromName":"Josh Triplett","fromEmail":"josh@joshtriplett.org","sentAt":"2017-11-10T17:52:58Z","receivedAt":"2017-11-10T17:53:10Z","isPatch":true,"sender":{"key":"josh@joshtriplett.org","avatar":"https://avatars.githubusercontent.com/u/162737?v=4"},"body":"On Fri, Nov 10, 2017 at 03:02:50PM +0000, Adam Dinwoodie wrote:\n> The examples and common practice for adding markers such as \"RFC\" or\n> \"v2\" to the subject of patch emails is to have them within the same\n> brackets as the \"PATCH\" text, not after the closing bracket. Further,\n> the practice of `git format-patch` and the like, as well as what appears\n> to be the more common pratice on the mailing list, is to use \"[RFC\n> PATCH]\", not \"[PATCH/RFC]\".\n> \n> Update the SubmittingPatches article to match and to reference the\n> `format-patch` helper arguments, and also make some minor text\n> clarifications in the area.\n> \n> Signed-off-by: Adam Dinwoodie \n> Helped-by: Eric Sunshine \n\nThis looks great! Thank you for updating this documentation.\n\nReviewed-by: Josh Triplett \n\n> ---\n> \n> Notes:\n> Changes since v3:\n> - Clarified meaning of \"RFC\" per Eric's suggestion\n> - Made the impact of --subject-prefix and friends clearer per Eric's\n> suggestion\n> \n> Thank you for your nitpicking, Eric, it's useful and very much\n> appreciated :)\n> \n> Documentation/SubmittingPatches | 19 ++++++++++++-------\n> 1 file changed, 12 insertions(+), 7 deletions(-)\n> \n> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\n> index 558d465b6..89f239071 100644\n> --- a/Documentation/SubmittingPatches\n> +++ b/Documentation/SubmittingPatches\n> @@ -184,21 +184,26 @@ lose tabs that way if you are not careful.\n> \n> It is a common convention to prefix your subject line with\n> [PATCH]. This lets people easily distinguish patches from other\n> -e-mail discussions. Use of additional markers after PATCH and\n> -the closing bracket to mark the nature of the patch is also\n> -encouraged. E.g. [PATCH/RFC] is often used when the patch is\n> -not ready to be applied but it is for discussion, [PATCH v2],\n> -[PATCH v3] etc. are often seen when you are sending an update to\n> -what you have previously sent.\n> +e-mail discussions. Use of markers in addition to PATCH within\n> +the brackets to describe the nature of the patch is also\n> +encouraged. E.g. [RFC PATCH] (where RFC stands for \"request for\n> +comments\") is often used to indicate a patch needs further\n> +discussion before being accepted, [PATCH v2], [PATCH v3] etc.\n> +are often seen when you are sending an update to what you have\n> +previously sent.\n> \n> -\"git format-patch\" command follows the best current practice to\n> +The \"git format-patch\" command follows the best current practice to\n> format the body of an e-mail message. At the beginning of the\n> patch should come your commit message, ending with the\n> Signed-off-by: lines, and a line that consists of three dashes,\n> followed by the diffstat information and the patch itself. If\n> you are forwarding a patch from somebody else, optionally, at\n> the beginning of the e-mail message just before the commit\n> message starts, you can put a \"From: \" line to name that person.\n> +To change the default \"[PATCH]\" in the subject to \"[]\", use\n> +`git format-patch --subject-prefix=`. As a shortcut, you\n> +can use `--rfc` instead of `--subject-prefix=\"RFC PATCH\"`, or\n> +`-v ` instead of `--subject-prefix=\"PATCH v\"`.\n> \n> You often want to add additional explanation about the patch,\n> other than the commit message itself. Place such \"cover letter\"\n> -- \n> 2.14.3\n> \n"}]}