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

[Glen Choo <chooglen@google.com>]

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>
---
Thanks for the helpful comments on v1! v2 aims to clear up other
ambiguities from v1 and to propose a specific workflow for readers.

Changes since v1:

* recommend that readers reuse the `psuh` topic branch for v2
* recommend that readers mark their v1 topic branch
* add a link to the range-diff docs
* change the v2 glob pattern to `psuh/v2-*.patch` to match the v1 example
* explicitly call out the v2 glob pattern so that readers will be extra
  careful

Interdiff against v1:
  diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
  index add1c2bba9..790bf1e8b5 100644
  --- a/Documentation/MyFirstContribution.txt
  +++ b/Documentation/MyFirstContribution.txt
  @@ -1029,27 +1029,29 @@ kidding - be patient!)
   [[v2-git-send-email]]
   === Sending v2
   
  -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.
   
  -Let's write v2 as its own topic branch, because this will make some things more
  -convenient later on. Create the `psuh-v2` branch like so:
  +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:
   
   ----
  -$ git checkout -b psuh-v2 psuh
  +$ git checkout psuh
  +$ git branch psuh-v1
   ----
   
  -When 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:
  +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:
   
   ----
  -$ git format-patch -v2 --range-diff psuh..psuh-v2 --cover-letter -o psuh/ master..psuh
  +$ git format-patch -v2 --cover-letter -o psuh/ --range-diff master..psuh-v1 master..
   ----
   
  -The `--range-diff psuh..psuh-v2` parameter tells `format-patch` to include a
  -range diff between `psuh` and `psuh-v2`. This helps tell reviewers about the
  -differences between your v1 and v2 patches.
  +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
  @@ -1058,8 +1060,10 @@ prefixing them with "[PATCH V2]" instead of "[PATCH]", and your range-diff will
   be prefaced with "Range-diff against v1".
   
   Afer you run this command, `format-patch` will output the patches to the `psuh/`
  -directory, alongside the v1 patches. That's fine, but be careful when you are
  -ready to send them.
  +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
  @@ -1097,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]]

 Documentation/MyFirstContribution.txt | 41 ++++++++++++++++++++-------
 1 file changed, 30 insertions(+), 11 deletions(-)

diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
index 015cf24631..790bf1e8b5 100644
--- a/Documentation/MyFirstContribution.txt
+++ b/Documentation/MyFirstContribution.txt
@@ -1029,22 +1029,41 @@ kidding - be patient!)
 [[v2-git-send-email]]
 === Sending v2
 
-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
+----
 
-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:
 
 ----
-$ 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".
+
+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]]
-- 
2.33.0.464.g1972c5931b-goog