Re: [PATCH v2] MyFirstContribution: Document --range-diff option when writing v2

From: Eric Sunshine <sunshine@sunshineco.com>
Date: Sep 21, 2021, 04:59 UTC
Message-ID: <CAPig+cR8ZRGVrNsf6nbBsjuLt768fr=SB+bY_bD+tQpkzrL7FA@mail.gmail.com>
In-Reply-To: <20210920223226.25877-1-chooglen@google.com>

On Mon, Sep 20, 2021 at 10:22 PM Glen Choo <chooglen@google.com> wrote:

Show 15 quoted lines

> In the "Sending v2" section, readers are directed to create v2 patches
> without using --range-diff. However, it is customary to include a
> range-diff against the v1 patches as a reviewer aid.
>
> Update the "Sending v2" section to suggest a simple workflow that uses
> the --range-diff option. Also include some explanation for -v2 and
> --range-diff to help the reader understand the importance.
>
> Signed-off-by: Glen Choo <chooglen@google.com>
> ---
> diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
> @@ -1029,22 +1029,41 @@ kidding - be patient!)
> +Make your changes with `git rebase -i`. Once you're ready with the next
> +iteration of your patch, the process is fairly similar to before. Generate your
> +patches again, but with some new flags:

I wonder if "Make your changes with `git rebase -i`" is a bit too terse for newcomers to understand. Perhaps a bit more verbose:

    Refine your patch series by using `git rebase -i` to adjust
    commits based upon reviewer comments. Once the patch series is
    ready for submission, generate your patches again, but with some
    new flags:

Show 7 quoted lines

>  ----
> +$ git format-patch -v2 --cover-letter -o psuh/ --range-diff master..psuh-v1 master..
>  ----
>
> +The `--range-diff master..psuh-v1` parameter tells `format-patch` to include a
> +range-diff between `psuh-v1` and `psuh` (see linkgit:git-range-diff[1]). This
> +helps tell reviewers about the differences between your v1 and v2 patches.

This leaves dangling the question of where the range-diff is placed. Maybe say:

    ... tells `format-patch` to include a range-diff between ... in
    the cover letter.

Show 5 quoted lines

> +The `-v2` parameter tells `format-patch` to output "v2" patches. For instance,
> +you may notice that your v2 patches, are all named like
> +`v2-000n-my-commit-subject.patch`. `-v2` will also format your patches by
> +prefixing them with "[PATCH V2]" instead of "[PATCH]", and your range-diff will
> +be prefaced with "Range-diff against v1".

s/V2/v2/

Show 5 quoted lines

> +Afer you run this command, `format-patch` will output the patches to the `psuh/`
> +directory, alongside the v1 patches. Using a single directory makes it easy to
> +refer to the old v1 patches while proofreading the v2 patches, but you will need
> +to be careful to send out only the v2 patches. We will use a pattern like
> +"psuh/v2-*.patch" ("psuh/*.patch" would match v1 and v2 patches).

To avoid any sort of confusion, perhaps:

    ... "psuh/v2-*.patch" (not "psuh/*.patch" which would match v1 and
    v2 patches)