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

[Weijie Yuan <wy@wyuan.org>]

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.
(Edit: the last point is discussed by Junio[3], which is improved in v3)

Since I am the newbie here, please tell me how to attribute the credit
to Patrick. Thank you Patrick!
(Edit: finished with the Helped-by trailer in v2)

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

---
Changes in v3:

  - Reworked the substantial-rework case.  Instead of suggesting that
    authors send a new version sooner, the text now advises authors not
    to rush out an updated version before reviewing the larger changes
    carefully.  It recommends replying to the review that prompted the
    rewrite, saying that a substantial rework is planned, and pointing
    out which parts of the current series will become obsolete.

  - Dropped the advice that a topic close to being accepted may justify
    a quicker reroll.

  - Removed "how close the topic is to being accepted" from the short
    reroll-timing guidance in Documentation/SubmittingPatches.

  - Updated the commit message of patch 2 accordingly.


Changes in v2:

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

  - Add "social interactions" in commit message.

  I didn't do any changes for Patrick's comments in [a]:

  > 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?

  Thinking about whether to delete/revert or not. Comments welcome.

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

  - Add a trailer to thank Patrick.

  Suggestions from Junio:

  - Mention that waiting between rerolls gives reviewers across time
    zones a fair chance to participate.
  - Mention that waiting also encourages authors to polish patches
    before sending them.

[a] <ai_7Wh7hrD8PZozg@pks.im>
---
base commit: 700432b2ba (topic flush before -rc1 (batch 1), 2026-06-15)

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

 Documentation/MyFirstContribution.adoc | 34 ++++++++++++++++++++++----
 Documentation/SubmittingPatches        | 23 ++++++++++++++---
 2 files changed, 48 insertions(+), 9 deletions(-)

Range-diff against v2:
1:  4bb1efe71d = 1:  4bb1efe71d doc: encourage review replies before rerolling
2:  496a08c74d ! 2:  e1050a6ef5 doc: advise batching patch rerolls
    @@ Commit message
         time to comment regardless of their time zones.
     
         Mention factors that can affect the timing, such as series size, review
    -    depth, substantial rework, and how close the topic is to being accepted.
    -    Also point out that avoiding rapid rerolls encourages authors to polish
    -    each version before sending it, so reviewers can focus on substantial
    -    issues.
    +    depth, and substantial rework. Also point out that avoiding rapid
    +    rerolls encourages authors to polish each version before sending it, so
    +    reviewers can focus on substantial issues.
     
         Helped-by: Patrick Steinhardt <ps@pks.im>
         Signed-off-by: Weijie Yuan <wy@wyuan.org>
    @@ Documentation/MyFirstContribution.adoc: previous one" patches over 2 days), revi
     +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.
    ++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]]
    @@ Documentation/SubmittingPatches: area.
     -input and avoids unnecessary churn from many rapid iterations.
     +input, gives reviewers in different time zones a fair chance to comment,
     +and avoids unnecessary churn from many rapid iterations.  Waiting also
    -+encourages you to polish each version before sending it, so reviewers can
    -+focus on substantial issues rather than typos or other small mistakes.
    ++encourages you to polish each version before sending it, so reviewers
    ++can focus on substantial issues rather than typos or other small
    ++mistakes. (only changes textwidth here)
     ++
     +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.
    ++series per day, while considering the size of the series and the depth
    ++of review.
      
      . These early update iterations are expected to be full replacements,
        not incremental updates on top of what you posted already.  If you
-- 
2.54.0