MyFirstContribution: Document --range-diff option when writing v2
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> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Glen Choo committed
Sep 22, 2021 at 13:22 UTC
1cc31e15293f2a26d330fe15f236949071d2c316
1 file changed
+31
-11
Documentation/MyFirstContribution.txt
+31
-11
@@ -1029,22 +1029,42 @@ kidding - be patient!)
1029
[[v2-git-send-email]]
1030
=== Sending v2
1031
1032
-Skip ahead to <<reviewing,Responding to Reviews>> for information on how to
1033
-handle comments from reviewers. Continue this section when your topic branch is
1034
-shaped the way you want it to look for your patchset v2.
1032
+This section will focus on how to send a v2 of your patchset. To learn what
1033
+should go into v2, skip ahead to <<reviewing,Responding to Reviews>> for
1034
+information on how to handle comments from reviewers.
1035
+
1036
+We'll reuse our `psuh` topic branch for v2. Before we make any changes, we'll
1037
+mark the tip of our v1 branch for easy reference:
1038
1036
-When you're ready with the next iteration of your patch, the process is fairly
1037
-similar.
1039
+----
1040
+$ git checkout psuh
1041
+$ git branch psuh-v1
1042
+----
1043
1039
-First, generate your v2 patches again:
1044
+Refine your patch series by using `git rebase -i` to adjust commits based upon
1045
+reviewer comments. Once the patch series is ready for submission, generate your
1046
+patches again, but with some new flags:
1047
1048
----
1042
-$ git format-patch -v2 --cover-letter -o psuh/ master..psuh
1049
+$ git format-patch -v2 --cover-letter -o psuh/ --range-diff master..psuh-v1 master..
1050
----
1051
1045
-This will add your v2 patches, all named like `v2-000n-my-commit-subject.patch`,
1046
-to the `psuh/` directory. You may notice that they are sitting alongside the v1
1047
-patches; that's fine, but be careful when you are ready to send them.
1052
+The `--range-diff master..psuh-v1` parameter tells `format-patch` to include a
1053
+range-diff between `psuh-v1` and `psuh` in the cover letter (see
1054
+linkgit:git-range-diff[1]). This helps tell reviewers about the differences
1055
+between your v1 and v2 patches.
1056
+
1057
+The `-v2` parameter tells `format-patch` to output your patches
1058
+as version "2". For instance, you may notice that your v2 patches are
1059
+all named like `v2-000n-my-commit-subject.patch`. `-v2` will also format
1060
+your patches by prefixing them with "[PATCH v2]" instead of "[PATCH]",
1061
+and your range-diff will be prefaced with "Range-diff against v1".
1062
+
1063
+Afer you run this command, `format-patch` will output the patches to the `psuh/`
1064
+directory, alongside the v1 patches. Using a single directory makes it easy to
1065
+refer to the old v1 patches while proofreading the v2 patches, but you will need
1066
+to be careful to send out only the v2 patches. We will use a pattern like
1067
+"psuh/v2-*.patch" (not "psuh/*.patch", which would match v1 and v2 patches).
1068
1069
Edit your cover letter again. Now is a good time to mention what's different
1070
between your last version and now, if it's something significant. You do not
@@ -1082,7 +1102,7 @@ to the command:
1102
----
1103
$ git send-email --to=target@example.com
1104
--in-reply-to="<foo.12345.author@example.com>"
1085
- psuh/v2*
1105
+ psuh/v2-*.patch
1106
----
1107
1108
[[single-patch]]