doc: advise batching patch rerolls
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 regardless of their time zones. Mention factors that can affect the timing, such as series size, review 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> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Weijie Yuan committed
Jun 21, 2026 at 16:05 UTC
477172636160c9729a2c4ae4aca4b3bcf0d4d83a
2 files changed
+33
-2
Documentation/MyFirstContribution.adoc
+22
@@ -1330,6 +1330,28 @@ previous one" patches over 2 days), reviewers would strongly prefer if a
1330
single polished version came 2 days later instead, and that version with
1331
fewer mistakes were the only one they would need to review.
1332
1333
+This consideration applies not only when going from the initial patch to v2,
1334
+but also to later iterations of the same series. There is no fixed rule for how
1335
+long to wait before sending a new version. A useful default is to send at most
1336
+one new version of the same patch series per day. This gives multiple reviewers
1337
+time to comment, gives reviewers across time zones a fair chance to
1338
+participate, lets you batch feedback together, and gives you time to think
1339
+through the comments you received. Knowing that you should not immediately send
1340
+another version also encourages you to review the patches more carefully before
1341
+sending them, catch small mistakes such as typos and off-by-one errors
1342
+yourself, and let reviewers spend more of their attention on design,
1343
+algorithms, and other substantial issues.
1344
+
1345
+The right timing depends on the topic and the feedback. Larger series usually
1346
+need more review time. If the only comments so far are minor, such as typo
1347
+fixes, it often makes sense to wait a little longer in case deeper reviews are
1348
+still coming. If the comments call for substantial rework, do not rush out an
1349
+updated version before you have reviewed the larger changes carefully. Instead,
1350
+reply to the review that prompted the rewrite, say that you are preparing a
1351
+substantial rework, and mention which parts of the current series will become
1352
+obsolete so reviewers can avoid spending time on them until the updated series
1353
+is ready.
1354
+
1355
1356
[[reviewing]]
1357
=== Responding to Reviews
Documentation/SubmittingPatches
+11
-2
@@ -58,7 +58,15 @@ area.
58
It is often beneficial to allow some time for reviewers to provide
59
feedback before sending a new version, rather than sending an updated
60
series immediately after receiving a review. This helps collect broader
61
-input and avoids unnecessary churn from many rapid iterations.
61
+input, gives reviewers in different time zones a fair chance to comment,
62
+and avoids unnecessary churn from many rapid iterations. Waiting also
63
+encourages you to polish each version before sending it, so reviewers
64
+can focus on substantial issues rather than typos or other small
65
+mistakes.
66
++
67
+As a rough default, avoid sending more than one new version of the same
68
+series per day, while considering the size of the series and the depth
69
+of review.
70
71
. These early update iterations are expected to be full replacements,
72
not incremental updates on top of what you posted already. If you
@@ -619,7 +627,8 @@ letter" message (see below), the first patch, or the respective preceding patch.
627
Here is a link:MyFirstContribution.html#v2-git-send-email[step-by-step guide] on
628
how to submit updated versions of a patch series. Before sending another
629
version, make sure you have answered meaningful review comments in the existing
622
-discussion.
630
+discussion. Also give reviewers enough time to comment before sending another
631
+version.
632
633
If your log message (including your name on the
634
`Signed-off-by` trailer) is not writable in ASCII, make sure that