In the "Sending V2" section, readers are directed to create v2 patches without using --range-diff. However, it is custom to include a range diff against the v1 patches as a reviewer aid. Update the "Sending V2" section to include 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@xxxxxxxxxx> --- 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
