[RFC PATCH 0/2] doc: clarify review replies and reroll timing

[RFC PATCH 0/2] doc: clarify review replies and reroll timing

[Weijie Yuan]

Hi,

This small series updates the 2 documentations: MyFirstContribution and
SubmittingPatches.

The first patch clarifies that review feedback should not be answered
only by sending a new version of the patches, which is talked in [1].
Contributors are encouraged to and should discuss their planned response in
the existing review thread, so that the next version does not become the
only place where reviewers can infer the author's reasoning.

The second patch is originally from an email from Patrick [2], which
documents a rough expectation around reroll frequency.

Patrick suggests: There is no hard rule for when to send a new version,
but batching feedback and avoiding multiple rerolls of the same series
in a single day is a useful default. The text also mentions factors that
may affect this, such as the size of the series, the depth of review,
and whether the topic is close to being picked up.

Since I am the newbie here, please tell me how to attribute the credit
to Patrick. Thank you Patrick!

I am sending this as RFC because I think my wording is quite rough, and
there must be a better way to express all of these, including how to
manage the structures of both these two documents. Any comments are
appreciated, thank you!

[1]: <xmqq7bo5nf31.fsf@gitster.g>
[2]: <aietF4BX1Ewt3cpG@pks.im>

Weijie Yuan (2):
  doc: encourage review replies before rerolling
  doc: advise batching patch rerolls

 Documentation/MyFirstContribution.adoc | 27 +++++++++++++++++++++-----
 Documentation/SubmittingPatches        | 17 +++++++++++++---
 2 files changed, 36 insertions(+), 8 deletions(-)

-- 
2.54.0

[RFC PATCH 1/2] doc: encourage review replies before rerolling

[Weijie Yuan]

Review feedback should not be answered only by sending a new patch
version. Encourage contributors to discuss their planned response in the
mailing-list thread before rerolling.

This makes the author's reasoning explicit before the next version is
prepared, instead of forcing reviewers to infer it from the rerolled
patches.

Signed-off-by: Weijie Yuan <wy@wyuan.org>
---
 Documentation/MyFirstContribution.adoc | 12 +++++++-----
 Documentation/SubmittingPatches        | 12 +++++++++---
 2 files changed, 16 insertions(+), 8 deletions(-)

diff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc
index 0e2a9313ce..59891e3c14 100644
--- a/Documentation/MyFirstContribution.adoc
+++ b/Documentation/MyFirstContribution.adoc
@@ -1423,11 +1423,13 @@ fewer mistakes were the only one they would need to review.
 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, notifying the reviewer that you have
-made the change suggested, feel the original is better, or that the comment
-inspired you to do something a new way which is superior to both the original
-and the suggested change. This way reviewers don't need to inspect your v2 to
-figure out whether you implemented their comment or not.
+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
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 6b83b6c89e..d8ad7fb73e 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -48,8 +48,12 @@ area.
 
 . You get comments and suggestions for improvements.  You may even get
   them in an "on top of your change" patch form.  You are expected to
-  respond to them with "Reply-All" on the mailing list, while taking
-  them into account while preparing an updated set of patches.
+  respond to them with "Reply-All" on the mailing list, instead of
+  letting an updated patch series be your only response.  Tell
+  reviewers which suggestions you plan to use, which ones you disagree
+  with, and when a comment leads you to consider a different approach.
+  Use these replies and any follow-up discussion as input when
+  preparing an updated set of patches.
 +
 It is often beneficial to allow some time for reviewers to provide
 feedback before sending a new version, rather than sending an updated
@@ -639,7 +643,9 @@ grouped into their own e-mail thread to help readers find all parts of the
 series.  To that end, send them as replies to either an additional "cover
 letter" message (see below), the first patch, or the respective preceding patch.
 Here is a link:MyFirstContribution.html#v2-git-send-email[step-by-step guide] on
-how to submit updated versions of a patch series.
+how to submit updated versions of a patch series.  Before sending another
+version, make sure you have answered meaningful review comments in the existing
+discussion.
 
 If your log message (including your name on the
 `Signed-off-by:` trailer) is not writable in ASCII, make sure that
-- 
2.54.0

[RFC PATCH 2/2] doc: advise batching patch rerolls

[Weijie Yuan]

Contributors often need guidance on how quickly to send later iterations
of a patch series. Add a rough default of no more than one new version
of the same series per day so feedback can be batched and reviewers have
time to comment.

Mention factors that can affect the timing, such as series size, review
depth, substantial rework, and how close the topic is to being accepted.

Signed-off-by: Weijie Yuan <wy@wyuan.org>
---
 Documentation/MyFirstContribution.adoc | 15 +++++++++++++++
 Documentation/SubmittingPatches        |  7 ++++++-
 2 files changed, 21 insertions(+), 1 deletion(-)

diff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc
index 59891e3c14..9d76c72d05 100644
--- a/Documentation/MyFirstContribution.adoc
+++ b/Documentation/MyFirstContribution.adoc
@@ -1416,6 +1416,21 @@ 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, lets you batch feedback together, and gives you time to think
+through the comments you received.
+
+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 require substantial rework, sending a new version
+sooner may save reviewers from spending time on a version you already know will
+change significantly. If the topic is close to being accepted and the remaining
+comments are small, a quicker new version may also be fine.
+
 
 [[reviewing]]
 === Responding to Reviews
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index d8ad7fb73e..1bc2684c54 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -59,6 +59,10 @@ It is often beneficial to allow some time for reviewers to provide
 feedback before sending a new version, rather than sending an updated
 series immediately after receiving a review. This helps collect broader
 input and avoids unnecessary churn from many rapid iterations.
++
+As a rough default, avoid sending more than one new version of the same
+series per day, while considering the size of the series, the depth of
+review, and how close the topic is to being accepted.
 
 . These early update iterations are expected to be full replacements,
   not incremental updates on top of what you posted already.  If you
@@ -645,7 +649,8 @@ letter" message (see below), the first patch, or the respective preceding patch.
 Here is a link:MyFirstContribution.html#v2-git-send-email[step-by-step guide] on
 how to submit updated versions of a patch series.  Before sending another
 version, make sure you have answered meaningful review comments in the existing
-discussion.
+discussion.  Also give reviewers enough time to comment before sending another
+version.
 
 If your log message (including your name on the
 `Signed-off-by:` trailer) is not writable in ASCII, make sure that
-- 
2.54.0

Re: [RFC PATCH 2/2] doc: advise batching patch rerolls

[Junio C Hamano]

Weijie Yuan <wy@wyuan.org> writes:

> Contributors often need guidance on how quickly to send later iterations
> of a patch series. Add a rough default of no more than one new version
> of the same series per day so feedback can be batched and reviewers have
> time to comment.
>
> Mention factors that can affect the timing, such as series size, review
> depth, substantial rework, and how close the topic is to being accepted.

Another good thing to discourage yourself from rerolling too quickly
is that such a practice forces you to think twice and be very
careful before sending patches out.  As you have only one chance to
get it right before, say, 24 hours, you'd want to make sure that you
would not distract your reviewers with stupid typoes, off-by-one
errors, and such, and concentrate their reviews more on what matters
more, i.e., the higher level design, choice of algorithms, etc.

> +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, lets you batch feedback together, and gives you time to think
> +through the comments you received.

And the 24-hour gives equal chance to comment on your patches to
anybody no matter where they live ;-)

I see you CC'ed Patrick, and I am sure he'll give us more useful
suggestions than I do here ;-)

Thanks.

Re: [RFC PATCH 2/2] doc: advise batching patch rerolls

[Weijie Yuan]

On Sat, Jun 13, 2026 at 09:02:39AM -0700, Junio C Hamano wrote:
> Weijie Yuan <wy@wyuan.org> writes:
> 
> > Contributors often need guidance on how quickly to send later iterations
> > of a patch series. Add a rough default of no more than one new version
> > of the same series per day so feedback can be batched and reviewers have
> > time to comment.
> >
> > Mention factors that can affect the timing, such as series size, review
> > depth, substantial rework, and how close the topic is to being accepted.
> 
> Another good thing to discourage yourself from rerolling too quickly
> is that such a practice forces you to think twice and be very
> careful before sending patches out.  As you have only one chance to
> get it right before, say, 24 hours, you'd want to make sure that you
> would not distract your reviewers with stupid typoes, off-by-one
> errors, and such, and concentrate their reviews more on what matters
> more, i.e., the higher level design, choice of algorithms, etc.
> 
> > +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, lets you batch feedback together, and gives you time to think
> > +through the comments you received.
> 
> And the 24-hour gives equal chance to comment on your patches to
> anybody no matter where they live ;-)

Thanks for your comments above! Let me think about how to integrate
these contents with the patch.

> I see you CC'ed Patrick, and I am sure he'll give us more useful
> suggestions than I do here ;-)

This is his practical advice, and I just stole Patrick´s wording, to be
fair ;-) so of course I should CC him and let him know I am a wording
thief :-P, hope it wouldn't disturb him ;-) 

Thank you very much.

Re: [RFC PATCH 1/2] doc: encourage review replies before rerolling

[Patrick Steinhardt]

On Sat, Jun 13, 2026 at 10:08:30PM +0800, Weijie Yuan wrote:
> Review feedback should not be answered only by sending a new patch
> version. Encourage contributors to discuss their planned response in the
> mailing-list thread before rerolling.
> 
> This makes the author's reasoning explicit before the next version is
> prepared, instead of forcing reviewers to infer it from the rerolled
> patches.

Not only that, but it also encourages more social interactions between
contributors.

> diff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc
> index 0e2a9313ce..59891e3c14 100644
> --- a/Documentation/MyFirstContribution.adoc
> +++ b/Documentation/MyFirstContribution.adoc
> @@ -1423,11 +1423,13 @@ fewer mistakes were the only one they would need to review.
>  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, notifying the reviewer that you have
> -made the change suggested, feel the original is better, or that the comment
> -inspired you to do something a new way which is superior to both the original
> -and the suggested change. This way reviewers don't need to inspect your v2 to
> -figure out whether you implemented their comment or not.
> +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

I feel like the new version doesn't really add anything significant to
this paragraph that it didn't already say before your patch, but it does
so with more words.

I'm of course biased though, so maybe more words help newcomers?

> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
> index 6b83b6c89e..d8ad7fb73e 100644
> --- a/Documentation/SubmittingPatches
> +++ b/Documentation/SubmittingPatches
> @@ -48,8 +48,12 @@ area.
>  
>  . You get comments and suggestions for improvements.  You may even get
>    them in an "on top of your change" patch form.  You are expected to
> -  respond to them with "Reply-All" on the mailing list, while taking
> -  them into account while preparing an updated set of patches.
> +  respond to them with "Reply-All" on the mailing list, instead of
> +  letting an updated patch series be your only response.  Tell
> +  reviewers which suggestions you plan to use, which ones you disagree
> +  with, and when a comment leads you to consider a different approach.
> +  Use these replies and any follow-up discussion as input when
> +  preparing an updated set of patches.

This change I agree with though, as it highlights what kind of
discussions we expect to happen.

> @@ -639,7 +643,9 @@ grouped into their own e-mail thread to help readers find all parts of the
>  series.  To that end, send them as replies to either an additional "cover
>  letter" message (see below), the first patch, or the respective preceding patch.
>  Here is a link:MyFirstContribution.html#v2-git-send-email[step-by-step guide] on
> -how to submit updated versions of a patch series.
> +how to submit updated versions of a patch series.  Before sending another
> +version, make sure you have answered meaningful review comments in the existing
> +discussion.

This change is probably good, as well.

Overall it's a bit on the annoying side that we have to always make sure
to update both SubmittingPatches and MyFirstContribution in tandem.
Makes me wonder whether they are mostly redundant and whether it would
make sense to eventually merge them. But that's a tangent and not
anything that needs to be addressed in this (or any other) patch series.

Patrick

Re: [RFC PATCH 2/2] doc: advise batching patch rerolls

[Patrick Steinhardt]

On Sun, Jun 14, 2026 at 01:05:04AM +0800, Weijie Yuan wrote:
> On Sat, Jun 13, 2026 at 09:02:39AM -0700, Junio C Hamano wrote:
> > Weijie Yuan <wy@wyuan.org> writes:
> > 
> > > Contributors often need guidance on how quickly to send later iterations
> > > of a patch series. Add a rough default of no more than one new version
> > > of the same series per day so feedback can be batched and reviewers have
> > > time to comment.
> > >
> > > Mention factors that can affect the timing, such as series size, review
> > > depth, substantial rework, and how close the topic is to being accepted.
> > 
> > Another good thing to discourage yourself from rerolling too quickly
> > is that such a practice forces you to think twice and be very
> > careful before sending patches out.  As you have only one chance to
> > get it right before, say, 24 hours, you'd want to make sure that you
> > would not distract your reviewers with stupid typoes, off-by-one
> > errors, and such, and concentrate their reviews more on what matters
> > more, i.e., the higher level design, choice of algorithms, etc.
> > 
> > > +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, lets you batch feedback together, and gives you time to think
> > > +through the comments you received.
> > 
> > And the 24-hour gives equal chance to comment on your patches to
> > anybody no matter where they live ;-)
> 
> Thanks for your comments above! Let me think about how to integrate
> these contents with the patch.
> 
> > I see you CC'ed Patrick, and I am sure he'll give us more useful
> > suggestions than I do here ;-)
> 
> This is his practical advice, and I just stole Patrick´s wording, to be
> fair ;-) so of course I should CC him and let him know I am a wording
> thief :-P, hope it wouldn't disturb him ;-) 

Indeed, so I don't really have anything else to add here.

By the way, talking about mailing list etiquette: in scenarios like this
it makes sense to add a Helped-by trailer. That would've serviced as
hint to Junio that I was already involved, and it gives credit to that
other contributor. I myself don't care much about the latter part
anymore, but newer contributors might.

And no, I don't mind at all that you "stole" my wording. Quite on the
contrary, I'm happy you picked up my thoughts and cared enough to put
them into a nice patch series :)

Thanks!

Patrick

Re: [RFC PATCH 1/2] doc: encourage review replies before rerolling

[Weijie Yuan]

On Mon, Jun 15, 2026 at 03:17:14PM +0200, Patrick Steinhardt wrote:
> On Sat, Jun 13, 2026 at 10:08:30PM +0800, Weijie Yuan wrote:
> > Review feedback should not be answered only by sending a new patch
> > version. Encourage contributors to discuss their planned response in the
> > mailing-list thread before rerolling.
> > 
> > This makes the author's reasoning explicit before the next version is
> > prepared, instead of forcing reviewers to infer it from the rerolled
> > patches.
> 
> Not only that, but it also encourages more social interactions between
> contributors.

Thank you, yes, let me add "social interactions" in v2.

> > diff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc
> > index 0e2a9313ce..59891e3c14 100644
> > --- a/Documentation/MyFirstContribution.adoc
> > +++ b/Documentation/MyFirstContribution.adoc
> > @@ -1423,11 +1423,13 @@ fewer mistakes were the only one they would need to review.
> >  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, notifying the reviewer that you have
> > -made the change suggested, feel the original is better, or that the comment
> > -inspired you to do something a new way which is superior to both the original
> > -and the suggested change. This way reviewers don't need to inspect your v2 to
> > -figure out whether you implemented their comment or not.
> > +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
> 
> I feel like the new version doesn't really add anything significant to
> this paragraph that it didn't already say before your patch, but it does
> so with more words.
> 
> I'm of course biased though, so maybe more words help newcomers?

Yes, this diff only and merely emphasizes "use the normal response
first, rather than re-rerolling directly." a litte bit, as I described
in commit message. But indend, the existing sentence:

"This way reviewers don't need to inspect your v2 to
-figure out whether you implemented their comment or not."

basically already has the same meaning.

So it does seem a bit wordy, but in other words, explicitly emphasizing
what not to do and what to do instead is more straightforward and clear
for new contributors.

Then the newly added sentence can correspond with the existing content
at the end of this paragraph (of course, this doesn't really make much
sense.)

> Overall it's a bit on the annoying side that we have to always make sure
> to update both SubmittingPatches and MyFirstContribution in tandem.
> Makes me wonder whether they are mostly redundant and whether it would
> make sense to eventually merge them. But that's a tangent and not
> anything that needs to be addressed in this (or any other) patch series.

To be honest, when I first started reading and writing, I had this
feeling and confusion. Since I haven't gone through the history of these
two documents yet, I just completed the preset task first.

Overall, I feel that the two documents have overlapping parts as well as
their own distinct focuses, and like being intertwined with each other.

For new contributors, it seems more convenient to just look at one
document, rather than trying to understand how the two files are
cross-referenced with each other. (although I found some newcomers in
GitHub PR pages don't even read one!) But this is obviously not an easy
task for the writer.

Perhaps start a discussion in a separate thread? with all relevant
personnel? But I understand that writing documentation is time-consuming
and not easy.

Thank you very much.

Re: [RFC PATCH 2/2] doc: advise batching patch rerolls

[Weijie Yuan]

On Mon, Jun 15, 2026 at 03:17:19PM +0200, Patrick Steinhardt wrote:
> By the way, talking about mailing list etiquette: in scenarios like this
> it makes sense to add a Helped-by trailer. That would've serviced as
> hint to Junio that I was already involved, and it gives credit to that
> other contributor. I myself don't care much about the latter part
> anymore, but newer contributors might.

Got it. I'll add that trailer. My original intention was to directly
write a "Originally-from" instead of "Helped-by", because I didn't add
anything new at all ;-)

> And no, I don't mind at all that you "stole" my wording. Quite on the
> contrary, I'm happy you picked up my thoughts and cared enough to put
> them into a nice patch series :)
> 
> Thanks!
> 
> Patrick

I should be thanking you :-) I´d like to start by contributing through
these more basic tasks and gradually become involved in the community,
since my code patches would probably only create noise and meaningless
trouble on the mailing list at this point ;-)

Thanks!