Re: [PATCH v3] doc/SubmittingPatches: correct subject guidance
From: Eric Sunshine <hidden>
Date: 2017-11-09 16:10:34
On Thu, Nov 9, 2017 at 8:08 AM, Adam Dinwoodie [off-list ref] wrote:
quoted hunk ↗ jump to hunk
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 <redacted> ---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=<text>`. 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 "[<text>]", use
`git format-patch --subject-prefix=<text>`.
+can use `--rfc` instead of `--subject-prefix="RFC PATCH"`, or +`-v <n>` instead of `--subject-prefix="PATCH v<n>"`.
Overall, this is much easier to digest than the run-on sentence in v2. Thanks.