Re: [PATCH v4] doc/SubmittingPatches: correct subject guidance
- Date: Fri, 10 Nov 2017 09:52:58 -0800
- From: Josh Triplett <josh@xxxxxxxxxxxxxxxx>
- Subject: Re: [PATCH v4] doc/SubmittingPatches: correct subject guidance
On Fri, Nov 10, 2017 at 03:02:50PM +0000, 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, and also make some minor text
> clarifications in the area.
> Signed-off-by: Adam Dinwoodie <adam@xxxxxxxxxxxxx>
> Helped-by: Eric Sunshine <sunshine@xxxxxxxxxxxxxx>
This looks great! Thank you for updating this documentation.
Reviewed-by: Josh Triplett <josh@xxxxxxxxxxxxxxxx>
> Changes since v3:
> - Clarified meaning of "RFC" per Eric's suggestion
> - Made the impact of --subject-prefix and friends clearer per Eric's
> Thank you for your nitpicking, Eric, it's useful and very much
> appreciated :)
> Documentation/SubmittingPatches | 19 ++++++++++++-------
> 1 file changed, 12 insertions(+), 7 deletions(-)
> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
> index 558d465b6..89f239071 100644
> --- a/Documentation/SubmittingPatches
> +++ b/Documentation/SubmittingPatches
> @@ -184,21 +184,26 @@ 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
> -not ready to be applied but it is for discussion, [PATCH v2],
> -[PATCH v3] etc. are often seen when you are sending an update to
> -what you have previously sent.
> +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] (where RFC stands for "request for
> +comments") is often used to indicate a patch needs further
> +discussion before being accepted, [PATCH v2], [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 default "[PATCH]" in the subject to "[<text>]", use
> +`git format-patch --subject-prefix=<text>`. As a shortcut, you
> +can use `--rfc` instead of `--subject-prefix="RFC PATCH"`, or
> +`-v <n>` instead of `--subject-prefix="PATCH v<n>"`.
> You often want to add additional explanation about the patch,
> other than the commit message itself. Place such "cover letter"