Re: [PATCH v3] doc/SubmittingPatches: correct subject guidance

From: Eric Sunshine <sunshine@sunshineco.com>
Date: Nov 9, 2017, 16:10 UTC
Message-ID: <CAPig+cRADknKB7KxqcZVinwP9vmGh1tmUrySUND3hMTi7a+bag@mail.gmail.com>
In-Reply-To: <20171109130826.52132-1-adam@dinwoodie.org>

On Thu, Nov 9, 2017 at 8:08 AM, Adam Dinwoodie <adam@dinwoodie.org> wrote:

Show 23 quoted lines

> 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 <adam@dinwoodie.org>
> ---
> 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.

Show 14 quoted lines

>  [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.