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

[Bagas Sanjaya <bagasdotme@gmail.com>]

On 21/09/21 05.32, Glen Choo wrote:
> -Skip ahead to <<reviewing,Responding to Reviews>> for information on how to
> -handle comments from reviewers. Continue this section when your topic branch is
> -shaped the way you want it to look for your patchset v2.
> +This section will focus on how to send a v2 of your patchset. To learn what
> +should go into v2, skip ahead to <<reviewing,Responding to Reviews>> for
> +information on how to handle comments from reviewers.
> +
> +We'll reuse our `psuh` topic branch for v2. Before we make any changes, we'll
> +mark the tip of our v1 branch for easy reference:
>   
> -When you're ready with the next iteration of your patch, the process is fairly
> -similar.
> +----
> +$ git checkout psuh
> +$ git branch psuh-v1
> +----
>   

Alternatively we can branch off psuh-v2 from the original psuh:
----
$ git checkout psuh
$ git checkout -b psuh-v2
----

The original psuh thus become v1. To easily identify it, we can run:
----
$ git checkout psuh
$ git branch -M psuh-v1
----

> -First, generate your v2 patches again:
> +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:
>   

For completeness, we can say "Make your changes with `git rebase -i`. 
Actions that you have to select in the todo editor of rebase depend on 
reviewers' comments. For example, if they asked to squash a commit into 
previous one, say `pick` on the latter and `squash` on the former."

>   ----
> -$ git format-patch -v2 --cover-letter -o psuh/ master..psuh
> +$ git format-patch -v2 --cover-letter -o psuh/ --range-diff master..psuh-v1 master..
>   ----
>   
> -This will add your v2 patches, all named like `v2-000n-my-commit-subject.patch`,
> -to the `psuh/` directory. You may notice that they are sitting alongside the v1
> -patches; that's fine, but be careful when you are ready to send them.
> +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.
> +
> +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".
> +

More accurately, `-v 2` marks the patchset as second iteration of it.

> +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).
>   
>   Edit your cover letter again. Now is a good time to mention what's different
>   between your last version and now, if it's something significant. You do not
> @@ -1082,7 +1101,7 @@ to the command:
>   ----
>   $ git send-email --to=target@example.com
>   		 --in-reply-to="<foo.12345.author@example.com>"
> -		 psuh/v2*
> +		 psuh/v2-*.patch
>   ----
>   
>   [[single-patch]]
> 


-- 
An old man doll... just what I always wanted! - Clara