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

From

Glen Choo <chooglen@google.com>

Date

Sep 13, 2021, 19:48 UTC

Message-ID

<20210913194816.51182-1-chooglen@google.com>

Signed-off-by: Glen Choo <chooglen@google.com>
---
 Documentation/MyFirstContribution.txt | 29 ++++++++++++++++++++-------
 1 file changed, 22 insertions(+), 7 deletions(-)

diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
index 015cf24631..add1c2bba9 100644
--- a/Documentation/MyFirstContribution.txt
+++ b/Documentation/MyFirstContribution.txt
@@ -1033,18 +1033,33 @@ 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.
 
-When you're ready with the next iteration of your patch, the process is fairly
-similar.
+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:
 
-First, generate your v2 patches again:
+----
+$ git checkout -b psuh-v2 psuh
+----
+
+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:
 
 ----
-$ git format-patch -v2 --cover-letter -o psuh/ master..psuh
+$ git format-patch -v2 --range-diff psuh..psuh-v2 --cover-letter -o psuh/ master..psuh
 ----
 
-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 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 `-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. That's fine, but be careful when you are
+ready to send them.
 
 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

-- 
2.33.0.309.g3052b89438-goog