git/list[1] front-page[2] threads[3] people[4] search[5] about
 

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

From
Glen Choo <chooglen@google.com>
Date
Sep 22, 2021, 20:22 UTC
Message-ID
<20210922202218.7986-1-chooglen@google.com>
In-Reply-To
<20210920223226.25877-1-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>
---
This tightens up some of the language from v2, but is otherwise largely
similar. As always, thanks for the input!
Changes since v2:
* clarify that the range-diff is inserted into the cover letter
* describe -v2 as creating version "2" instead of "v2"
* fix typo in email prefix (s/V2/v2)
* explicitly compare the v2 glob pattern with the v1 glob pattern
Interdiff against v2:
  diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
  index 790bf1e8b5..b20bc8e914 100644
  --- a/Documentation/MyFirstContribution.txt
  +++ b/Documentation/MyFirstContribution.txt
  @@ -1041,8 +1041,8 @@ $ git checkout psuh
   $ git branch psuh-v1
   ----
   
  -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
  +Refine your patch series by using `git rebase -i` to adjust commits based upon
  +reviewer comments. Once the patch series is ready for submission, generate your
   patches again, but with some new flags:
   
   ----
  @@ -1050,20 +1050,21 @@ $ git format-patch -v2 --cover-letter -o psuh/ --range-diff master..psuh-v1 mast
   ----
   
   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.
  +range-diff between `psuh-v1` and `psuh` in the cover letter (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".
  +The `-v2` parameter tells `format-patch` to output your patches
  +as version "2". 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).
  +"psuh/v2-*.patch" (not "psuh/*.patch", which 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
 Documentation/MyFirstContribution.txt | 42 ++++++++++++++++++++-------
 1 file changed, 31 insertions(+), 11 deletions(-)
diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
index 015cf24631..b20bc8e914 100644
--- a/Documentation/MyFirstContribution.txt
+++ b/Documentation/MyFirstContribution.txt
@@ -1029,22 +1029,42 @@ 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:
+Refine your patch series by using `git rebase -i` to adjust commits based upon
+reviewer comments. Once the patch series is ready for submission, 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` in the cover letter (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 your patches
+as version "2". 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" (not "psuh/*.patch", which 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 +1102,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
Previous: Bagas Sanjaya
Message 22 of 22 in “MyFirstContribution: Document --range-diff option when writing v2”
  1. MyFirstContribution: Document --range-diff option when writing v2Glen Choo, Sep 13, 2021
  2. Eric SunshineSep 13, 2021
  3. Eric SunshineSep 13, 2021
  4. Junio C HamanoSep 13, 2021
  5. Glen ChooSep 14, 2021
  6. Junio C HamanoSep 14, 2021
  7. Bagas SanjayaSep 14, 2021
  8. Eric SunshineSep 14, 2021
  9. Bagas SanjayaSep 14, 2021
  10. MyFirstContribution: Document --range-diff option when writing v2Glen Choo, Sep 20, 2021
  11. Eric SunshineSep 21, 2021
  12. Glen ChooSep 21, 2021
  13. Glen ChooSep 21, 2021
  14. Glen ChooSep 21, 2021
  15. Bagas SanjayaSep 21, 2021
  16. Glen ChooSep 21, 2021
  17. Junio C HamanoSep 22, 2021
  18. Philip OakleySep 22, 2021
  19. Glen ChooSep 22, 2021
  20. Philip OakleySep 23, 2021
  21. Bagas SanjayaSep 23, 2021
  22. MyFirstContribution: Document --range-diff option when writing v2Glen Choo, Sep 22, 2021

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.