From: Eric Sunshine Date: Thu, 09 Nov 2017 16:10:27 GMT Subject: Re: [PATCH v3] doc/SubmittingPatches: correct subject guidance Message-ID: In-Reply-To: <20171109130826.52132-1-adam@dinwoodie.org> On Thu, Nov 9, 2017 at 8:08 AM, Adam Dinwoodie wrote: > The examples and common practice for adding markers such as "RFC" or > "v2" to the subject of patch emails is to have them within the same > brackets as the "PATCH" text, not after the closing bracket. Further, > the practice of `git format-patch` and the like, as well as what appears > to be the more common pratice on the mailing list, is to use "[RFC > PATCH]", not "[PATCH/RFC]". > > Update the SubmittingPatches article to match, and to reference the > `format-patch` helper arguments. > > Signed-off-by: Adam Dinwoodie > --- > diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches > @@ -184,21 +184,25 @@ lose tabs that way if you are not careful. > It is a common convention to prefix your subject line with > [PATCH]. This lets people easily distinguish patches from other > -e-mail discussions. Use of additional markers after PATCH and > -the closing bracket to mark the nature of the patch is also > -encouraged. E.g. [PATCH/RFC] is often used when the patch is > +e-mail discussions. Use of markers in addition to PATCH within > +the brackets to describe the nature of the patch is also > +encouraged. E.g. [RFC PATCH] is often used when the patch is > not ready to be applied but it is for discussion, [PATCH v2], Not a new problem, but since you're here cleaning this up, the "not ready to be applied but it is for discussion" makes for a clunky read. Perhaps something roughly like: E.g. [RFC PATCH] is often used to indicate that a patch needs further discussion ("request for comments") before being accepted. > [PATCH v3] etc. are often seen when you are sending an update to > what you have previously sent. > > -"git format-patch" command follows the best current practice to > +The "git format-patch" command follows the best current practice to > format the body of an e-mail message. At the beginning of the > patch should come your commit message, ending with the > Signed-off-by: lines, and a line that consists of three dashes, > followed by the diffstat information and the patch itself. If > you are forwarding a patch from somebody else, optionally, at > the beginning of the e-mail message just before the commit > message starts, you can put a "From: " line to name that person. > +To change the bracketed text at the start of the subject, use > +`git format-patch --subject-prefix=`. As a shortcut, you This may be nit-picky, but it took a bit of thought for me to work out what "bracketed text at the start of the subject" meant. I wonder if it would be clearer just to spell it out: To change the default "[PATCH]" in the subject to "[]", use `git format-patch --subject-prefix=`. > +can use `--rfc` instead of `--subject-prefix="RFC PATCH"`, or > +`-v ` instead of `--subject-prefix="PATCH v"`. Overall, this is much easier to digest than the run-on sentence in v2. Thanks.