[PATCH] MyFirstContribution: move preparation of v2 after review discussion

[PATCH] MyFirstContribution: move preparation of v2 after review discussion

[Junio C Hamano]

The text in the MyFirstContribution documentation tells readers how
to send v1, how to send v2, and then how to respond to reviews, in
this order.  It is unclear how much blame can be placed on this
text, but it somehow seems that senior community members need to
tell new contributors not to send updated interations of their
patches before having any review discussion on the current iteration
more often these days.

Here is an attempt to improve the text by moving "how to send v2"
part much late in the text flow, after discussiong what should
happen in the review discussion.

Strengthen the language about not sending the v2 out before engaging
in the discussion from "It is a good manners to do so" to "Do not
send v2 before you are done".

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/MyFirstContribution.adoc | 265 +++++++++++++++++----------------
 1 file changed, 137 insertions(+), 128 deletions(-)

diff --git c/Documentation/MyFirstContribution.adoc w/Documentation/MyFirstContribution.adoc
index 34bfa2e3a9..296ff97262 100644
--- c/Documentation/MyFirstContribution.adoc
+++ w/Documentation/MyFirstContribution.adoc
@@ -1171,87 +1171,6 @@ prompt for each patch that's about to go out. This gives you one last chance to
 edit or quit sending something (but again, don't edit code this way). Once you
 press `y` or `a` at these prompts your emails will be sent! Congratulations!
 
-Awesome, now the community will drop everything and review your changes. (Just
-kidding - be patient!)
-
-[[v2-git-send-email]]
-=== Sending 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:
-
-----
-$ git checkout psuh
-$ git branch psuh-v1
-----
-
-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/ --range-diff master..psuh-v1 master..
-----
-
-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".
-
-After 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
-need the exact same body in your second cover letter; focus on explaining to
-reviewers the changes you've made that may not be as visible.
-
-You will also need to go and find the Message-ID of your first cover letter.
-You can either note it when you send the first series, from the output of `git
-send-email`, or you can look it up on the
-https://lore.kernel.org/git[mailing list]. Find your cover letter in the
-archives, click on it, then click "permalink" or "raw" to reveal the Message-ID
-header. It should match:
-
-----
-Message-ID: <foo.12345.author@example.com>
-----
-
-Your Message-ID is `<foo.12345.author@example.com>`. This example will be used
-below as well; make sure to replace it with the correct Message-ID for your
-**first cover letter** - that is, for any subsequent version that you send,
-always use the Message-ID from v1.
-
-While you're looking at the email, you should also note who is CC'd, as it's
-common practice in the mailing list to keep all CCs on a thread. You can add
-these CC lines directly to your cover letter with a line like so in the header
-(before the Subject line):
-
-----
-CC: author@example.com, Othe R <other@example.com>
-----
-
-Now send the emails again, paying close attention to which messages you pass in
-to the command:
-
-----
-$ git send-email --to=target@example.com
-		 --in-reply-to="<foo.12345.author@example.com>"
-		 psuh/v2-*.patch
-----
 
 [[single-patch]]
 === Bonus Chapter: One-Patch Changes
@@ -1348,29 +1267,6 @@ Once you are happy with the result, send the series with:
 $ b4 send
 ----
 
-[[v2-b4]]
-=== Sending v2
-
-When you are ready to send a new iteration of your series, refine your
-patches as usual using linkgit:git-rebase[1]. Note that you typically want to
-rebase on top of the cover letter. You can configure an alias to enable easy
-rebases going forward:
-
----
-$ git config set alias.b4-rebase 'rebase "HEAD^{/--- b4-submit-tracking ---}"'
-$ git b4-rebase -i
----
-
-Before sending out the new version you should also update the cover letter with
-`b4 prep --edit-cover` to note the relevant changes compared to the previous
-version. You can inspect the changes between the two versions with `b4 prep
---compare-to=v1`.
-
-Same as with the first version, you can use `b4 send` to send out the second
-version. `b4` automatically bumps the version to `v2`, generates the range-diff
-against the previous iteration, and threads the new series as a reply to the
-cover letter of the first version.
-
 [[configure-b4]]
 === Configure b4
 
@@ -1438,34 +1334,38 @@ substantial rework, and mention which parts of the current series will become
 obsolete so reviewers can avoid spending time on them until the updated series
 is ready.
 
+No matter what mechanism you chose to use among GitGitGadget, `git
+send-email`, or `b4`, members of the community will have a chance to
+appreciate your brilliance and will respond with review comments in
+due course.
+
 
 [[reviewing]]
 === Responding to Reviews
 
-After a few days, you will hopefully receive a reply to your patchset with some
-comments. Woohoo! Now you can get back to work.
-
-It's good manners to reply to each comment in the mailing list discussion
-instead of letting the next version of your patch be your only response. Tell
-the reviewer whether you plan to make the suggested change, keep the original,
-or pursue a different approach. This way reviewers can respond to your reasoning
-before you spend time preparing a version they may not agree with, and later do
-not need to inspect your v2 to figure out whether you implemented their comment
-or not.
-
-Reviewers may ask you about what you wrote in the patchset, either in
-the proposed commit log message or in the changes themselves.  You
-should answer these questions in your response messages, but often the
-reason why reviewers asked these questions to understand what you meant
-to write is because your patchset needed clarification to be understood.
-
-Do not be satisfied by just answering their questions in your response
-and hear them say that they now understand what you wanted to say.
-Update your patches to clarify the points reviewers had trouble with,
-and prepare your v2; the words you used to explain your v1 to answer
-reviewers' questions may be useful thing to use.  Your goal is to make
-your v2 clear enough so that it becomes unnecessary for you to give the
-same explanation to the next person who reads it.
+After a few days, you will hopefully receive a reply to your patchset
+with some comments.
+
+
+Try to understand the reviewers' points, and ask questions if you do
+not understand what reviewers suggested.  Reviewers may also ask you
+about what you wrote in the patchset, either in the proposed commit
+log message or in the changes themselves.  You should answer these
+questions in your response messages, but often the reason why
+reviewers asked these questions to understand what you meant to write
+is because your patchset needed clarification to be understood.  Make
+a mental note that when you send an improved version of the patch,
+make sure you explain your patch clearly enough so that the next
+person do not have to ask the same question again.
+
+Try to find the best way to improve your patch they are commenting on
+together.  Until you are done discussing the current round of reviews
+with your reviewers, do not start coding, let alone sending the next
+version of your patch.  This way both you and your reviewers will save
+time.  Reviewers can respond to your reasoning before you spend time
+preparing a version they may not agree with, and later do not need to
+inspect your v2 to figure out whether you implemented their comment or
+not.
 
 If you are going to push back on a comment, be polite and explain why you feel
 your original is better; be prepared that the reviewer may still disagree with
@@ -1501,6 +1401,115 @@ changing history, but since it's local history which you haven't shared with
 anyone, that is okay for now! (Later, it may not make sense to do this; take a
 look at the section below this one for some context.)
 
+After review discussion concludes for the current iteration, you will
+work on an improved version of your patch, and you will send the "v2".
+
+
+[[v2-git-send-email]]
+=== Sending 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:
+
+----
+$ git checkout psuh
+$ git branch psuh-v1
+----
+
+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/ --range-diff master..psuh-v1 master..
+----
+
+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".
+
+After 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
+need the exact same body in your second cover letter; focus on explaining to
+reviewers the changes you've made that may not be as visible.
+
+You will also need to go and find the Message-ID of your first cover letter.
+You can either note it when you send the first series, from the output of `git
+send-email`, or you can look it up on the
+https://lore.kernel.org/git[mailing list]. Find your cover letter in the
+archives, click on it, then click "permalink" or "raw" to reveal the Message-ID
+header. It should match:
+
+----
+Message-ID: <foo.12345.author@example.com>
+----
+
+Your Message-ID is `<foo.12345.author@example.com>`. This example will be used
+below as well; make sure to replace it with the correct Message-ID for your
+**first cover letter** - that is, for any subsequent version that you send,
+always use the Message-ID from v1.
+
+While you're looking at the email, you should also note who is CC'd, as it's
+common practice in the mailing list to keep all CCs on a thread. You can add
+these CC lines directly to your cover letter with a line like so in the header
+(before the Subject line):
+
+----
+CC: author@example.com, Othe R <other@example.com>
+----
+
+Now send the emails again, paying close attention to which messages you pass in
+to the command:
+
+----
+$ git send-email --to=target@example.com
+		 --in-reply-to="<foo.12345.author@example.com>"
+		 psuh/v2-*.patch
+----
+
+[[v2-b4]]
+=== Sending v2
+
+When you are ready to send a new iteration of your series, refine your
+patches as usual using linkgit:git-rebase[1]. Note that you typically want to
+rebase on top of the cover letter. You can configure an alias to enable easy
+rebases going forward:
+
+---
+$ git config set alias.b4-rebase 'rebase "HEAD^{/--- b4-submit-tracking ---}"'
+$ git b4-rebase -i
+---
+
+Before sending out the new version you should also update the cover letter with
+`b4 prep --edit-cover` to note the relevant changes compared to the previous
+version. You can inspect the changes between the two versions with `b4 prep
+--compare-to=v1`.
+
+Same as with the first version, you can use `b4 send` to send out the second
+version. `b4` automatically bumps the version to `v2`, generates the range-diff
+against the previous iteration, and threads the new series as a reply to the
+cover letter of the first version.
+
+
+
+
 [[after-approval]]
 === After Review Approval
 

Re: [PATCH] MyFirstContribution: move preparation of v2 after review discussion

[Patrick Steinhardt]

On Mon, Oct 19, 2026 at 01:43:48PM -0700, Junio C Hamano wrote:
> The text in the MyFirstContribution documentation tells readers how
> to send v1, how to send v2, and then how to respond to reviews, in
> this order.  It is unclear how much blame can be placed on this
> text, but it somehow seems that senior community members need to
> tell new contributors not to send updated interations of their

s/interations/iterations/

> patches before having any review discussion on the current iteration
> more often these days.
> 
> Here is an attempt to improve the text by moving "how to send v2"
> part much late in the text flow, after discussiong what should
> happen in the review discussion.
> 
> Strengthen the language about not sending the v2 out before engaging
> in the discussion from "It is a good manners to do so" to "Do not
> send v2 before you are done".

Nit: I think this would have been easier to review if you first moved
stuff around without changing the language yet and only then changing it
in a second commit. Like this it's basically impossible to see what was
moved and what needs reviewing.

> diff --git c/Documentation/MyFirstContribution.adoc w/Documentation/MyFirstContribution.adoc
> index 34bfa2e3a9..296ff97262 100644
> --- c/Documentation/MyFirstContribution.adoc
> +++ w/Documentation/MyFirstContribution.adoc
[snip]

Now comes the rewritten part, everything above was simply moved.

> +After a few days, you will hopefully receive a reply to your patchset
> +with some comments.
> +
> +

Nit: two newlines.

> +Try to understand the reviewers' points, and ask questions if you do
> +not understand what reviewers suggested.  Reviewers may also ask you
> +about what you wrote in the patchset, either in the proposed commit
> +log message or in the changes themselves.  You should answer these
> +questions in your response messages, but often the reason why
> +reviewers asked these questions to understand what you meant to write
> +is because your patchset needed clarification to be understood.  Make
> +a mental note that when you send an improved version of the patch,
> +make sure you explain your patch clearly enough so that the next
> +person do not have to ask the same question again.

s/do/does/

> +Try to find the best way to improve your patch they are commenting on
> +together.  Until you are done discussing the current round of reviews
> +with your reviewers, do not start coding, let alone sending the next
> +version of your patch.

This may be a bit broad, as quite often I find myself exploring ideas
before I can properly respond to review feedback. But maybe it's better
to be this pushy given the recent trend of people not responding at all.

> This way both you and your reviewers will save
> +time.  Reviewers can respond to your reasoning before you spend time
> +preparing a version they may not agree with, and later do not need to
> +inspect your v2 to figure out whether you implemented their comment or
> +not.
>  
>  If you are going to push back on a comment, be polite and explain why you feel
>  your original is better; be prepared that the reviewer may still disagree with
> @@ -1501,6 +1401,115 @@ changing history, but since it's local history which you haven't shared with
>  anyone, that is okay for now! (Later, it may not make sense to do this; take a
>  look at the section below this one for some context.)
>  
> +After review discussion concludes for the current iteration, you will
> +work on an improved version of your patch, and you will send the "v2".

Makes sense.

[snip]
> +Same as with the first version, you can use `b4 send` to send out the second
> +version. `b4` automatically bumps the version to `v2`, generates the range-diff
> +against the previous iteration, and threads the new series as a reply to the
> +cover letter of the first version.
> +
> +
> +
> +

This is a lot of empty lines here :)




Thanks!

Patrick

Re: [PATCH] MyFirstContribution: move preparation of v2 after review discussion

[Junio C Hamano]

Patrick Steinhardt <ps@pks.im> writes:

> Nit: I think this would have been easier to review if you first moved
> stuff around without changing the language yet and only then changing it
> in a second commit. Like this it's basically impossible to see what was
> moved and what needs reviewing.

Yeah, I was thinking exactly that after sending it out.  Will do so
when I try it again after sleeping on the topic for a few days and
seeing other comments that hopefully will come in the meantime.

Thanks.

[PATCH v2 0/2] MyFirstContribution: discuss then reroll

[Junio C Hamano]

So here is a rerolled version of

    https://lore.kernel.org/git/xmqqa4o94e0r.fsf@gitster.g/

Two major differences are:

 * The shuffling of the order of descriptions, so that we discuss
   reviewing process before we talk about v2, is split out into a
   separate patch and has become [1/2].

 * Redundant caution against sending updates too quickly/often has
   been consolidated into one description, mixed with the new text
   I wrote for v1 and copyedited.  This is now [2/2].

The diff with v1 and the end image of this series is not really
worth showing, as the delta is large enough.

 1/2: MyFirstContribution: move "how to send v2" after discussing reviews
 2/2: MyFirstContribution: clarify that "reviewing" is a discussion

 Documentation/MyFirstContribution.adoc | 287 ++++++++++++-------------
 1 file changed, 139 insertions(+), 148 deletions(-)

-- 
2.56.0-321-g29a826976d

[PATCH v2 1/2] MyFirstContribution: move "how to send v2" after discussing reviews

[Junio C Hamano]

The MyFirstContribution document tells readers how to send v1, how
to send v2, and then how to respond to reviews, in that order.

It is unclear how much blame can be placed on this text, but senior
community members find themselves more and more frequently having to
tell new contributors not to send updated iterations of their patches
before having any review discussion on the current iteration.

As a small first step to rectify the situation, move the description
of how to send v2 so that it appears after we have told readers to
expect and respond to reviews on their first iteration.  This step
contains no text changes.  Only the ordering changes, which are
friendly to 'git diff --color-moved', are included here.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/MyFirstContribution.adoc | 204 ++++++++++++-------------
 1 file changed, 102 insertions(+), 102 deletions(-)

diff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc
index 34bfa2e3a9..682c797e3c 100644
--- a/Documentation/MyFirstContribution.adoc
+++ b/Documentation/MyFirstContribution.adoc
@@ -1174,85 +1174,6 @@ press `y` or `a` at these prompts your emails will be sent! Congratulations!
 Awesome, now the community will drop everything and review your changes. (Just
 kidding - be patient!)
 
-[[v2-git-send-email]]
-=== Sending 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:
-
-----
-$ git checkout psuh
-$ git branch psuh-v1
-----
-
-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/ --range-diff master..psuh-v1 master..
-----
-
-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".
-
-After 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
-need the exact same body in your second cover letter; focus on explaining to
-reviewers the changes you've made that may not be as visible.
-
-You will also need to go and find the Message-ID of your first cover letter.
-You can either note it when you send the first series, from the output of `git
-send-email`, or you can look it up on the
-https://lore.kernel.org/git[mailing list]. Find your cover letter in the
-archives, click on it, then click "permalink" or "raw" to reveal the Message-ID
-header. It should match:
-
-----
-Message-ID: <foo.12345.author@example.com>
-----
-
-Your Message-ID is `<foo.12345.author@example.com>`. This example will be used
-below as well; make sure to replace it with the correct Message-ID for your
-**first cover letter** - that is, for any subsequent version that you send,
-always use the Message-ID from v1.
-
-While you're looking at the email, you should also note who is CC'd, as it's
-common practice in the mailing list to keep all CCs on a thread. You can add
-these CC lines directly to your cover letter with a line like so in the header
-(before the Subject line):
-
-----
-CC: author@example.com, Othe R <other@example.com>
-----
-
-Now send the emails again, paying close attention to which messages you pass in
-to the command:
-
-----
-$ git send-email --to=target@example.com
-		 --in-reply-to="<foo.12345.author@example.com>"
-		 psuh/v2-*.patch
-----
-
 [[single-patch]]
 === Bonus Chapter: One-Patch Changes
 
@@ -1348,29 +1269,6 @@ Once you are happy with the result, send the series with:
 $ b4 send
 ----
 
-[[v2-b4]]
-=== Sending v2
-
-When you are ready to send a new iteration of your series, refine your
-patches as usual using linkgit:git-rebase[1]. Note that you typically want to
-rebase on top of the cover letter. You can configure an alias to enable easy
-rebases going forward:
-
----
-$ git config set alias.b4-rebase 'rebase "HEAD^{/--- b4-submit-tracking ---}"'
-$ git b4-rebase -i
----
-
-Before sending out the new version you should also update the cover letter with
-`b4 prep --edit-cover` to note the relevant changes compared to the previous
-version. You can inspect the changes between the two versions with `b4 prep
---compare-to=v1`.
-
-Same as with the first version, you can use `b4 send` to send out the second
-version. `b4` automatically bumps the version to `v2`, generates the range-diff
-against the previous iteration, and threads the new series as a reply to the
-cover letter of the first version.
-
 [[configure-b4]]
 === Configure b4
 
@@ -1501,6 +1399,108 @@ changing history, but since it's local history which you haven't shared with
 anyone, that is okay for now! (Later, it may not make sense to do this; take a
 look at the section below this one for some context.)
 
+[[v2-git-send-email]]
+=== Sending 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:
+
+----
+$ git checkout psuh
+$ git branch psuh-v1
+----
+
+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/ --range-diff master..psuh-v1 master..
+----
+
+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".
+
+After 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
+need the exact same body in your second cover letter; focus on explaining to
+reviewers the changes you've made that may not be as visible.
+
+You will also need to go and find the Message-ID of your first cover letter.
+You can either note it when you send the first series, from the output of `git
+send-email`, or you can look it up on the
+https://lore.kernel.org/git[mailing list]. Find your cover letter in the
+archives, click on it, then click "permalink" or "raw" to reveal the Message-ID
+header. It should match:
+
+----
+Message-ID: <foo.12345.author@example.com>
+----
+
+Your Message-ID is `<foo.12345.author@example.com>`. This example will be used
+below as well; make sure to replace it with the correct Message-ID for your
+**first cover letter** - that is, for any subsequent version that you send,
+always use the Message-ID from v1.
+
+While you're looking at the email, you should also note who is CC'd, as it's
+common practice in the mailing list to keep all CCs on a thread. You can add
+these CC lines directly to your cover letter with a line like so in the header
+(before the Subject line):
+
+----
+CC: author@example.com, Othe R <other@example.com>
+----
+
+Now send the emails again, paying close attention to which messages you pass in
+to the command:
+
+----
+$ git send-email --to=target@example.com
+		 --in-reply-to="<foo.12345.author@example.com>"
+		 psuh/v2-*.patch
+----
+
+[[v2-b4]]
+=== Sending v2
+
+When you are ready to send a new iteration of your series, refine your
+patches as usual using linkgit:git-rebase[1]. Note that you typically want to
+rebase on top of the cover letter. You can configure an alias to enable easy
+rebases going forward:
+
+---
+$ git config set alias.b4-rebase 'rebase "HEAD^{/--- b4-submit-tracking ---}"'
+$ git b4-rebase -i
+---
+
+Before sending out the new version you should also update the cover letter with
+`b4 prep --edit-cover` to note the relevant changes compared to the previous
+version. You can inspect the changes between the two versions with `b4 prep
+--compare-to=v1`.
+
+Same as with the first version, you can use `b4 send` to send out the second
+version. `b4` automatically bumps the version to `v2`, generates the range-diff
+against the previous iteration, and threads the new series as a reply to the
+cover letter of the first version.
+
 [[after-approval]]
 === After Review Approval
 
-- 
2.56.0-321-g29a826976d

[PATCH v2 2/2] MyFirstContribution: clarify that "reviewing" is a discussion

[Junio C Hamano]

The latter half of the "We sent our initial patch.  Now what?"
section largely duplicates the discussion on what to do after
getting a review, which is covered in the subsequent section.  Also,
the "Reviewing" section does not make it clear from the beginning
that reviewing is a process of discussion with your reviewers.

Rewrite the "Reviewing" section with stronger language to discourage
sending a 'v2' iteration before working together with the reviewers
to prepare for it.  In particular, replace the weak "it is a good
manners to do so" with a firmer "do not send v2 before you are
done."

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/MyFirstContribution.adoc | 78 +++++++++++---------------
 1 file changed, 32 insertions(+), 46 deletions(-)

diff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc
index 682c797e3c..3fd6587e5a 100644
--- a/Documentation/MyFirstContribution.adoc
+++ b/Documentation/MyFirstContribution.adoc
@@ -1314,56 +1314,42 @@ previous one" patches over 2 days), reviewers would strongly prefer if a
 single polished version came 2 days later instead, and that version with
 fewer mistakes were the only one they would need to review.
 
-This consideration applies not only when going from the initial patch to v2,
-but also to later iterations of the same series. There is no fixed rule for how
-long to wait before sending a new version. A useful default is to send at most
-one new version of the same patch series per day. This gives multiple reviewers
-time to comment, gives reviewers across time zones a fair chance to
-participate, lets you batch feedback together, and gives you time to think
-through the comments you received. Knowing that you should not immediately send
-another version also encourages you to review the patches more carefully before
-sending them, catch small mistakes such as typos and off-by-one errors
-yourself, and let reviewers spend more of their attention on design,
-algorithms, and other substantial issues.
-
-The right timing depends on the topic and the feedback. Larger series usually
-need more review time. If the only comments so far are minor, such as typo
-fixes, it often makes sense to wait a little longer in case deeper reviews are
-still coming. If the comments call for substantial rework, do not rush out an
-updated version before you have reviewed the larger changes carefully. Instead,
-reply to the review that prompted the rewrite, say that you are preparing a
-substantial rework, and mention which parts of the current series will become
-obsolete so reviewers can avoid spending time on them until the updated series
-is ready.
-
 
 [[reviewing]]
 === Responding to Reviews
 
-After a few days, you will hopefully receive a reply to your patchset with some
-comments. Woohoo! Now you can get back to work.
-
-It's good manners to reply to each comment in the mailing list discussion
-instead of letting the next version of your patch be your only response. Tell
-the reviewer whether you plan to make the suggested change, keep the original,
-or pursue a different approach. This way reviewers can respond to your reasoning
-before you spend time preparing a version they may not agree with, and later do
-not need to inspect your v2 to figure out whether you implemented their comment
-or not.
-
-Reviewers may ask you about what you wrote in the patchset, either in
-the proposed commit log message or in the changes themselves.  You
-should answer these questions in your response messages, but often the
-reason why reviewers asked these questions to understand what you meant
-to write is because your patchset needed clarification to be understood.
-
-Do not be satisfied by just answering their questions in your response
-and hear them say that they now understand what you wanted to say.
-Update your patches to clarify the points reviewers had trouble with,
-and prepare your v2; the words you used to explain your v1 to answer
-reviewers' questions may be useful thing to use.  Your goal is to make
-your v2 clear enough so that it becomes unnecessary for you to give the
-same explanation to the next person who reads it.
+After a few days, you will hopefully receive a reply to your patch
+series with some comments.  Carefully read them to understand the
+reviewers' perspective.  Do not hesitate to ask for clarification if
+you do not understand their suggestions.
+
+Reviewers may also ask about what you wrote in the patch series,
+either in the proposed commit log message or in the changes
+themselves.  Answer these questions in your response.  Often,
+reviewers ask because your patch series needs clarification to be
+understood; use this as feedback to improve the clarity of your
+writing.  When answering, remember to update the patch itself so that
+the next reader will not need to ask the same question.
+
+Do not start coding, much less send the next version of your patch,
+until you have finished discussing the current round of reviews with
+your reviewers.  This saves time for both you and your reviewers.
+They can respond to your reasoning before you spend time preparing a
+version they might reject, and they will not have to inspect your 'v2'
+to check if you addressed their concerns.
+
+Do not iterate too quickly.  Limiting yourself to at most one
+iteration of the same patch series per day is good practice; it takes
+time to fully discuss the current version before working on the next.
+This allows multiple reviewers to comment, gives participants in
+different time zones a fair chance to participate, lets you batch
+feedback, and gives you time to digest comments before coding again.
+
+Knowing that you cannot immediately send another version encourages
+you to review your patches more carefully before sending.  You can
+catch small mistakes like typos and off-by-one errors yourself,
+allowing reviewers to focus on design, algorithms, and other
+substantive issues.
 
 If you are going to push back on a comment, be polite and explain why you feel
 your original is better; be prepared that the reviewer may still disagree with
-- 
2.56.0-321-g29a826976d