{"thread":{"id":"65803","subject":"[RFC PATCH 0/2] doc: clarify review replies and reroll timing","startedAt":"2026-06-13T14:08:23Z","lastAt":"2026-06-25T06:55:08Z","messageCount":22,"participants":["Weijie Yuan","Junio C Hamano","Patrick Steinhardt"],"isPatch":true,"patchVersion":1,"patchTotal":2},"messages":[{"id":"545451","messageId":"cover.1781358364.git.wy@wyuan.org","threadId":"65803","inReplyTo":null,"subject":"[RFC PATCH 0/2] doc: clarify review replies and reroll timing","fromName":"Weijie Yuan","fromEmail":"wy@wyuan.org","sentAt":"2026-06-13T14:08:10Z","receivedAt":"2026-06-13T14:08:23Z","isPatch":true,"body":"Hi,\n\nThis small series updates the 2 documentations: MyFirstContribution and\nSubmittingPatches.\n\nThe first patch clarifies that review feedback should not be answered\nonly by sending a new version of the patches, which is talked in [1].\nContributors are encouraged to and should discuss their planned response in\nthe existing review thread, so that the next version does not become the\nonly place where reviewers can infer the author's reasoning.\n\nThe second patch is originally from an email from Patrick [2], which\ndocuments a rough expectation around reroll frequency.\n\nPatrick suggests: There is no hard rule for when to send a new version,\nbut batching feedback and avoiding multiple rerolls of the same series\nin a single day is a useful default. The text also mentions factors that\nmay affect this, such as the size of the series, the depth of review,\nand whether the topic is close to being picked up.\n\nSince I am the newbie here, please tell me how to attribute the credit\nto Patrick. Thank you Patrick!\n\nI am sending this as RFC because I think my wording is quite rough, and\nthere must be a better way to express all of these, including how to\nmanage the structures of both these two documents. Any comments are\nappreciated, thank you!\n\n[1]: \n[2]: \n\nWeijie Yuan (2):\n doc: encourage review replies before rerolling\n doc: advise batching patch rerolls\n\n Documentation/MyFirstContribution.adoc | 27 +++++++++++++++++++++-----\n Documentation/SubmittingPatches | 17 +++++++++++++---\n 2 files changed, 36 insertions(+), 8 deletions(-)\n\n-- \n2.54.0\n"},{"id":"545453","messageId":"68a1969c35cbc2d24af7a0d09c376ecf403c3591.1781358364.git.wy@wyuan.org","threadId":"65803","inReplyTo":"cover.1781358364.git.wy@wyuan.org","subject":"[RFC PATCH 1/2] doc: encourage review replies before rerolling","fromName":"Weijie Yuan","fromEmail":"wy@wyuan.org","sentAt":"2026-06-13T14:08:30Z","receivedAt":"2026-06-13T14:08:59Z","isPatch":true,"body":"Review feedback should not be answered only by sending a new patch\nversion. Encourage contributors to discuss their planned response in the\nmailing-list thread before rerolling.\n\nThis makes the author's reasoning explicit before the next version is\nprepared, instead of forcing reviewers to infer it from the rerolled\npatches.\n\nSigned-off-by: Weijie Yuan \n---\n Documentation/MyFirstContribution.adoc | 12 +++++++-----\n Documentation/SubmittingPatches | 12 +++++++++---\n 2 files changed, 16 insertions(+), 8 deletions(-)\n\ndiff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc\nindex 0e2a9313ce..59891e3c14 100644\n--- a/Documentation/MyFirstContribution.adoc\n+++ b/Documentation/MyFirstContribution.adoc\n@@ -1423,11 +1423,13 @@ fewer mistakes were the only one they would need to review.\n After a few days, you will hopefully receive a reply to your patchset with some\n comments. Woohoo! Now you can get back to work.\n \n-It's good manners to reply to each comment, notifying the reviewer that you have\n-made the change suggested, feel the original is better, or that the comment\n-inspired you to do something a new way which is superior to both the original\n-and the suggested change. This way reviewers don't need to inspect your v2 to\n-figure out whether you implemented their comment or not.\n+It's good manners to reply to each comment in the mailing list discussion\n+instead of letting the next version of your patch be your only response. Tell\n+the reviewer whether you plan to make the suggested change, keep the original,\n+or pursue a different approach. This way reviewers can respond to your reasoning\n+before you spend time preparing a version they may not agree with, and later do\n+not need to inspect your v2 to figure out whether you implemented their comment\n+or not.\n \n Reviewers may ask you about what you wrote in the patchset, either in\n the proposed commit log message or in the changes themselves. You\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex 6b83b6c89e..d8ad7fb73e 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -48,8 +48,12 @@ area.\n \n . You get comments and suggestions for improvements. You may even get\n them in an \"on top of your change\" patch form. You are expected to\n- respond to them with \"Reply-All\" on the mailing list, while taking\n- them into account while preparing an updated set of patches.\n+ respond to them with \"Reply-All\" on the mailing list, instead of\n+ letting an updated patch series be your only response. Tell\n+ reviewers which suggestions you plan to use, which ones you disagree\n+ with, and when a comment leads you to consider a different approach.\n+ Use these replies and any follow-up discussion as input when\n+ preparing an updated set of patches.\n +\n It is often beneficial to allow some time for reviewers to provide\n feedback before sending a new version, rather than sending an updated\n@@ -639,7 +643,9 @@ grouped into their own e-mail thread to help readers find all parts of the\n series. To that end, send them as replies to either an additional \"cover\n letter\" message (see below), the first patch, or the respective preceding patch.\n Here is a link:MyFirstContribution.html#v2-git-send-email[step-by-step guide] on\n-how to submit updated versions of a patch series.\n+how to submit updated versions of a patch series. Before sending another\n+version, make sure you have answered meaningful review comments in the existing\n+discussion.\n \n If your log message (including your name on the\n `Signed-off-by:` trailer) is not writable in ASCII, make sure that\n-- \n2.54.0\n\n"},{"id":"545454","messageId":"8166623d1599fca2cd4614889e4a69b2006c12c1.1781358364.git.wy@wyuan.org","threadId":"65803","inReplyTo":"cover.1781358364.git.wy@wyuan.org","subject":"[RFC PATCH 2/2] doc: advise batching patch rerolls","fromName":"Weijie Yuan","fromEmail":"wy@wyuan.org","sentAt":"2026-06-13T14:09:06Z","receivedAt":"2026-06-13T14:09:34Z","isPatch":true,"body":"Contributors often need guidance on how quickly to send later iterations\nof a patch series. Add a rough default of no more than one new version\nof the same series per day so feedback can be batched and reviewers have\ntime to comment.\n\nMention factors that can affect the timing, such as series size, review\ndepth, substantial rework, and how close the topic is to being accepted.\n\nSigned-off-by: Weijie Yuan \n---\n Documentation/MyFirstContribution.adoc | 15 +++++++++++++++\n Documentation/SubmittingPatches | 7 ++++++-\n 2 files changed, 21 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc\nindex 59891e3c14..9d76c72d05 100644\n--- a/Documentation/MyFirstContribution.adoc\n+++ b/Documentation/MyFirstContribution.adoc\n@@ -1416,6 +1416,21 @@ previous one\" patches over 2 days), reviewers would strongly prefer if a\n single polished version came 2 days later instead, and that version with\n fewer mistakes were the only one they would need to review.\n \n+This consideration applies not only when going from the initial patch to v2, but\n+also to later iterations of the same series. There is no fixed rule for how long\n+to wait before sending a new version. A useful default is to send at most one\n+new version of the same patch series per day. This gives multiple reviewers time\n+to comment, lets you batch feedback together, and gives you time to think\n+through the comments you received.\n+\n+The right timing depends on the topic and the feedback. Larger series usually\n+need more review time. If the only comments so far are minor, such as typo\n+fixes, it often makes sense to wait a little longer in case deeper reviews are\n+still coming. If the comments require substantial rework, sending a new version\n+sooner may save reviewers from spending time on a version you already know will\n+change significantly. If the topic is close to being accepted and the remaining\n+comments are small, a quicker new version may also be fine.\n+\n \n [[reviewing]]\n === Responding to Reviews\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex d8ad7fb73e..1bc2684c54 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -59,6 +59,10 @@ It is often beneficial to allow some time for reviewers to provide\n feedback before sending a new version, rather than sending an updated\n series immediately after receiving a review. This helps collect broader\n input and avoids unnecessary churn from many rapid iterations.\n++\n+As a rough default, avoid sending more than one new version of the same\n+series per day, while considering the size of the series, the depth of\n+review, and how close the topic is to being accepted.\n \n . These early update iterations are expected to be full replacements,\n not incremental updates on top of what you posted already. If you\n@@ -645,7 +649,8 @@ letter\" message (see below), the first patch, or the respective preceding patch.\n Here is a link:MyFirstContribution.html#v2-git-send-email[step-by-step guide] on\n how to submit updated versions of a patch series. Before sending another\n version, make sure you have answered meaningful review comments in the existing\n-discussion.\n+discussion. Also give reviewers enough time to comment before sending another\n+version.\n \n If your log message (including your name on the\n `Signed-off-by:` trailer) is not writable in ASCII, make sure that\n-- \n2.54.0\n\n"},{"id":"545459","messageId":"xmqqwlw2e8dc.fsf@gitster.g","threadId":"65803","inReplyTo":"8166623d1599fca2cd4614889e4a69b2006c12c1.1781358364.git.wy@wyuan.org","subject":"Re: [RFC PATCH 2/2] doc: advise batching patch rerolls","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-06-13T16:02:39Z","receivedAt":"2026-06-13T16:02:41Z","isPatch":true,"body":"Weijie Yuan writes:\n\n> Contributors often need guidance on how quickly to send later iterations\n> of a patch series. Add a rough default of no more than one new version\n> of the same series per day so feedback can be batched and reviewers have\n> time to comment.\n>\n> Mention factors that can affect the timing, such as series size, review\n> depth, substantial rework, and how close the topic is to being accepted.\n\nAnother good thing to discourage yourself from rerolling too quickly\nis that such a practice forces you to think twice and be very\ncareful before sending patches out. As you have only one chance to\nget it right before, say, 24 hours, you'd want to make sure that you\nwould not distract your reviewers with stupid typoes, off-by-one\nerrors, and such, and concentrate their reviews more on what matters\nmore, i.e., the higher level design, choice of algorithms, etc.\n\n> +This consideration applies not only when going from the initial patch to v2, but\n> +also to later iterations of the same series. There is no fixed rule for how long\n> +to wait before sending a new version. A useful default is to send at most one\n> +new version of the same patch series per day. This gives multiple reviewers time\n> +to comment, lets you batch feedback together, and gives you time to think\n> +through the comments you received.\n\nAnd the 24-hour gives equal chance to comment on your patches to\nanybody no matter where they live ;-)\n\nI see you CC'ed Patrick, and I am sure he'll give us more useful\nsuggestions than I do here ;-)\n\nThanks.\n"},{"id":"545463","messageId":"ai2NwMS-i_UTWR5T@wyuan.org","threadId":"65803","inReplyTo":"xmqqwlw2e8dc.fsf@gitster.g","subject":"Re: [RFC PATCH 2/2] doc: advise batching patch rerolls","fromName":"Weijie Yuan","fromEmail":"wy@wyuan.org","sentAt":"2026-06-13T17:05:04Z","receivedAt":"2026-06-13T17:06:03Z","isPatch":true,"body":"On Sat, Jun 13, 2026 at 09:02:39AM -0700, Junio C Hamano wrote:\n> Weijie Yuan writes:\n> \n> > Contributors often need guidance on how quickly to send later iterations\n> > of a patch series. Add a rough default of no more than one new version\n> > of the same series per day so feedback can be batched and reviewers have\n> > time to comment.\n> >\n> > Mention factors that can affect the timing, such as series size, review\n> > depth, substantial rework, and how close the topic is to being accepted.\n> \n> Another good thing to discourage yourself from rerolling too quickly\n> is that such a practice forces you to think twice and be very\n> careful before sending patches out. As you have only one chance to\n> get it right before, say, 24 hours, you'd want to make sure that you\n> would not distract your reviewers with stupid typoes, off-by-one\n> errors, and such, and concentrate their reviews more on what matters\n> more, i.e., the higher level design, choice of algorithms, etc.\n> \n> > +This consideration applies not only when going from the initial patch to v2, but\n> > +also to later iterations of the same series. There is no fixed rule for how long\n> > +to wait before sending a new version. A useful default is to send at most one\n> > +new version of the same patch series per day. This gives multiple reviewers time\n> > +to comment, lets you batch feedback together, and gives you time to think\n> > +through the comments you received.\n> \n> And the 24-hour gives equal chance to comment on your patches to\n> anybody no matter where they live ;-)\n\nThanks for your comments above! Let me think about how to integrate\nthese contents with the patch.\n\n> I see you CC'ed Patrick, and I am sure he'll give us more useful\n> suggestions than I do here ;-)\n\nThis is his practical advice, and I just stole Patrick´s wording, to be\nfair ;-) so of course I should CC him and let him know I am a wording\nthief :-P, hope it wouldn't disturb him ;-) \n\nThank you very much.\n"},{"id":"545561","messageId":"ai_7Wh7hrD8PZozg@pks.im","threadId":"65803","inReplyTo":"68a1969c35cbc2d24af7a0d09c376ecf403c3591.1781358364.git.wy@wyuan.org","subject":"Re: [RFC PATCH 1/2] doc: encourage review replies before rerolling","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-06-15T13:17:14Z","receivedAt":"2026-06-15T13:17:20Z","isPatch":true,"body":"On Sat, Jun 13, 2026 at 10:08:30PM +0800, Weijie Yuan wrote:\n> Review feedback should not be answered only by sending a new patch\n> version. Encourage contributors to discuss their planned response in the\n> mailing-list thread before rerolling.\n> \n> This makes the author's reasoning explicit before the next version is\n> prepared, instead of forcing reviewers to infer it from the rerolled\n> patches.\n\nNot only that, but it also encourages more social interactions between\ncontributors.\n\n> diff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc\n> index 0e2a9313ce..59891e3c14 100644\n> --- a/Documentation/MyFirstContribution.adoc\n> +++ b/Documentation/MyFirstContribution.adoc\n> @@ -1423,11 +1423,13 @@ fewer mistakes were the only one they would need to review.\n> After a few days, you will hopefully receive a reply to your patchset with some\n> comments. Woohoo! Now you can get back to work.\n> \n> -It's good manners to reply to each comment, notifying the reviewer that you have\n> -made the change suggested, feel the original is better, or that the comment\n> -inspired you to do something a new way which is superior to both the original\n> -and the suggested change. This way reviewers don't need to inspect your v2 to\n> -figure out whether you implemented their comment or not.\n> +It's good manners to reply to each comment in the mailing list discussion\n> +instead of letting the next version of your patch be your only response. Tell\n> +the reviewer whether you plan to make the suggested change, keep the original,\n> +or pursue a different approach. This way reviewers can respond to your reasoning\n> +before you spend time preparing a version they may not agree with, and later do\n> +not need to inspect your v2 to figure out whether you implemented their comment\n> +or not.\n> \n> Reviewers may ask you about what you wrote in the patchset, either in\n> the proposed commit log message or in the changes themselves. You\n\nI feel like the new version doesn't really add anything significant to\nthis paragraph that it didn't already say before your patch, but it does\nso with more words.\n\nI'm of course biased though, so maybe more words help newcomers?\n\n> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\n> index 6b83b6c89e..d8ad7fb73e 100644\n> --- a/Documentation/SubmittingPatches\n> +++ b/Documentation/SubmittingPatches\n> @@ -48,8 +48,12 @@ area.\n> \n> . You get comments and suggestions for improvements. You may even get\n> them in an \"on top of your change\" patch form. You are expected to\n> - respond to them with \"Reply-All\" on the mailing list, while taking\n> - them into account while preparing an updated set of patches.\n> + respond to them with \"Reply-All\" on the mailing list, instead of\n> + letting an updated patch series be your only response. Tell\n> + reviewers which suggestions you plan to use, which ones you disagree\n> + with, and when a comment leads you to consider a different approach.\n> + Use these replies and any follow-up discussion as input when\n> + preparing an updated set of patches.\n\nThis change I agree with though, as it highlights what kind of\ndiscussions we expect to happen.\n\n> @@ -639,7 +643,9 @@ grouped into their own e-mail thread to help readers find all parts of the\n> series. To that end, send them as replies to either an additional \"cover\n> letter\" message (see below), the first patch, or the respective preceding patch.\n> Here is a link:MyFirstContribution.html#v2-git-send-email[step-by-step guide] on\n> -how to submit updated versions of a patch series.\n> +how to submit updated versions of a patch series. Before sending another\n> +version, make sure you have answered meaningful review comments in the existing\n> +discussion.\n\nThis change is probably good, as well.\n\nOverall it's a bit on the annoying side that we have to always make sure\nto update both SubmittingPatches and MyFirstContribution in tandem.\nMakes me wonder whether they are mostly redundant and whether it would\nmake sense to eventually merge them. But that's a tangent and not\nanything that needs to be addressed in this (or any other) patch series.\n\nPatrick\n"},{"id":"545562","messageId":"ai_7X_QY0u1CWJ7s@pks.im","threadId":"65803","inReplyTo":"ai2NwMS-i_UTWR5T@wyuan.org","subject":"Re: [RFC PATCH 2/2] doc: advise batching patch rerolls","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-06-15T13:17:19Z","receivedAt":"2026-06-15T13:17:24Z","isPatch":true,"body":"On Sun, Jun 14, 2026 at 01:05:04AM +0800, Weijie Yuan wrote:\n> On Sat, Jun 13, 2026 at 09:02:39AM -0700, Junio C Hamano wrote:\n> > Weijie Yuan writes:\n> > \n> > > Contributors often need guidance on how quickly to send later iterations\n> > > of a patch series. Add a rough default of no more than one new version\n> > > of the same series per day so feedback can be batched and reviewers have\n> > > time to comment.\n> > >\n> > > Mention factors that can affect the timing, such as series size, review\n> > > depth, substantial rework, and how close the topic is to being accepted.\n> > \n> > Another good thing to discourage yourself from rerolling too quickly\n> > is that such a practice forces you to think twice and be very\n> > careful before sending patches out. As you have only one chance to\n> > get it right before, say, 24 hours, you'd want to make sure that you\n> > would not distract your reviewers with stupid typoes, off-by-one\n> > errors, and such, and concentrate their reviews more on what matters\n> > more, i.e., the higher level design, choice of algorithms, etc.\n> > \n> > > +This consideration applies not only when going from the initial patch to v2, but\n> > > +also to later iterations of the same series. There is no fixed rule for how long\n> > > +to wait before sending a new version. A useful default is to send at most one\n> > > +new version of the same patch series per day. This gives multiple reviewers time\n> > > +to comment, lets you batch feedback together, and gives you time to think\n> > > +through the comments you received.\n> > \n> > And the 24-hour gives equal chance to comment on your patches to\n> > anybody no matter where they live ;-)\n> \n> Thanks for your comments above! Let me think about how to integrate\n> these contents with the patch.\n> \n> > I see you CC'ed Patrick, and I am sure he'll give us more useful\n> > suggestions than I do here ;-)\n> \n> This is his practical advice, and I just stole Patrick´s wording, to be\n> fair ;-) so of course I should CC him and let him know I am a wording\n> thief :-P, hope it wouldn't disturb him ;-) \n\nIndeed, so I don't really have anything else to add here.\n\nBy the way, talking about mailing list etiquette: in scenarios like this\nit makes sense to add a Helped-by trailer. That would've serviced as\nhint to Junio that I was already involved, and it gives credit to that\nother contributor. I myself don't care much about the latter part\nanymore, but newer contributors might.\n\nAnd no, I don't mind at all that you \"stole\" my wording. Quite on the\ncontrary, I'm happy you picked up my thoughts and cared enough to put\nthem into a nice patch series :)\n\nThanks!\n\nPatrick\n"},{"id":"545583","messageId":"ajANsC5pfuk0PAn1@wyuan.org","threadId":"65803","inReplyTo":"ai_7Wh7hrD8PZozg@pks.im","subject":"Re: [RFC PATCH 1/2] doc: encourage review replies before rerolling","fromName":"Weijie Yuan","fromEmail":"wy@wyuan.org","sentAt":"2026-06-15T14:35:28Z","receivedAt":"2026-06-15T14:36:27Z","isPatch":true,"body":"On Mon, Jun 15, 2026 at 03:17:14PM +0200, Patrick Steinhardt wrote:\n> On Sat, Jun 13, 2026 at 10:08:30PM +0800, Weijie Yuan wrote:\n> > Review feedback should not be answered only by sending a new patch\n> > version. Encourage contributors to discuss their planned response in the\n> > mailing-list thread before rerolling.\n> > \n> > This makes the author's reasoning explicit before the next version is\n> > prepared, instead of forcing reviewers to infer it from the rerolled\n> > patches.\n> \n> Not only that, but it also encourages more social interactions between\n> contributors.\n\nThank you, yes, let me add \"social interactions\" in v2.\n\n> > diff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc\n> > index 0e2a9313ce..59891e3c14 100644\n> > --- a/Documentation/MyFirstContribution.adoc\n> > +++ b/Documentation/MyFirstContribution.adoc\n> > @@ -1423,11 +1423,13 @@ fewer mistakes were the only one they would need to review.\n> > After a few days, you will hopefully receive a reply to your patchset with some\n> > comments. Woohoo! Now you can get back to work.\n> > \n> > -It's good manners to reply to each comment, notifying the reviewer that you have\n> > -made the change suggested, feel the original is better, or that the comment\n> > -inspired you to do something a new way which is superior to both the original\n> > -and the suggested change. This way reviewers don't need to inspect your v2 to\n> > -figure out whether you implemented their comment or not.\n> > +It's good manners to reply to each comment in the mailing list discussion\n> > +instead of letting the next version of your patch be your only response. Tell\n> > +the reviewer whether you plan to make the suggested change, keep the original,\n> > +or pursue a different approach. This way reviewers can respond to your reasoning\n> > +before you spend time preparing a version they may not agree with, and later do\n> > +not need to inspect your v2 to figure out whether you implemented their comment\n> > +or not.\n> > \n> > Reviewers may ask you about what you wrote in the patchset, either in\n> > the proposed commit log message or in the changes themselves. You\n> \n> I feel like the new version doesn't really add anything significant to\n> this paragraph that it didn't already say before your patch, but it does\n> so with more words.\n> \n> I'm of course biased though, so maybe more words help newcomers?\n\nYes, this diff only and merely emphasizes \"use the normal response\nfirst, rather than re-rerolling directly.\" a litte bit, as I described\nin commit message. But indend, the existing sentence:\n\n\"This way reviewers don't need to inspect your v2 to\n-figure out whether you implemented their comment or not.\"\n\nbasically already has the same meaning.\n\nSo it does seem a bit wordy, but in other words, explicitly emphasizing\nwhat not to do and what to do instead is more straightforward and clear\nfor new contributors.\n\nThen the newly added sentence can correspond with the existing content\nat the end of this paragraph (of course, this doesn't really make much\nsense.)\n\n> Overall it's a bit on the annoying side that we have to always make sure\n> to update both SubmittingPatches and MyFirstContribution in tandem.\n> Makes me wonder whether they are mostly redundant and whether it would\n> make sense to eventually merge them. But that's a tangent and not\n> anything that needs to be addressed in this (or any other) patch series.\n\nTo be honest, when I first started reading and writing, I had this\nfeeling and confusion. Since I haven't gone through the history of these\ntwo documents yet, I just completed the preset task first.\n\nOverall, I feel that the two documents have overlapping parts as well as\ntheir own distinct focuses, and like being intertwined with each other.\n\nFor new contributors, it seems more convenient to just look at one\ndocument, rather than trying to understand how the two files are\ncross-referenced with each other. (although I found some newcomers in\nGitHub PR pages don't even read one!) But this is obviously not an easy\ntask for the writer.\n\nPerhaps start a discussion in a separate thread? with all relevant\npersonnel? But I understand that writing documentation is time-consuming\nand not easy.\n\nThank you very much.\n"},{"id":"545584","messageId":"ajAQ9BhPsFXjC13D@wyuan.org","threadId":"65803","inReplyTo":"ai_7X_QY0u1CWJ7s@pks.im","subject":"Re: [RFC PATCH 2/2] doc: advise batching patch rerolls","fromName":"Weijie Yuan","fromEmail":"wy@wyuan.org","sentAt":"2026-06-15T14:49:24Z","receivedAt":"2026-06-15T14:49:52Z","isPatch":true,"body":"On Mon, Jun 15, 2026 at 03:17:19PM +0200, Patrick Steinhardt wrote:\n> By the way, talking about mailing list etiquette: in scenarios like this\n> it makes sense to add a Helped-by trailer. That would've serviced as\n> hint to Junio that I was already involved, and it gives credit to that\n> other contributor. I myself don't care much about the latter part\n> anymore, but newer contributors might.\n\nGot it. I'll add that trailer. My original intention was to directly\nwrite a \"Originally-from\" instead of \"Helped-by\", because I didn't add\nanything new at all ;-)\n\n> And no, I don't mind at all that you \"stole\" my wording. Quite on the\n> contrary, I'm happy you picked up my thoughts and cared enough to put\n> them into a nice patch series :)\n> \n> Thanks!\n> \n> Patrick\n\nI should be thanking you :-) I´d like to start by contributing through\nthese more basic tasks and gradually become involved in the community,\nsince my code patches would probably only create noise and meaningless\ntrouble on the mailing list at this point ;-)\n\nThanks!\n"},{"id":"545773","messageId":"cover.1781714757.git.wy@wyuan.org","threadId":"65803","inReplyTo":"cover.1781358364.git.wy@wyuan.org","subject":"[PATCH v2 0/2] doc: clarify review replies and reroll timing","fromName":"Weijie Yuan","fromEmail":"wy@wyuan.org","sentAt":"2026-06-17T16:48:22Z","receivedAt":"2026-06-17T16:48:42Z","isPatch":true,"body":"Hi,\n\nThis small series updates the 2 documentations: MyFirstContribution and\nSubmittingPatches.\n\nThe first patch clarifies that review feedback should not be answered\nonly by sending a new version of the patches, which is talked in [1].\nContributors are encouraged to and should discuss their planned response in\nthe existing review thread, so that the next version does not become the\nonly place where reviewers can infer the author's reasoning.\n\nThe second patch is originally from an email from Patrick [2], which\ndocuments a rough expectation around reroll frequency.\n\nPatrick suggests: There is no hard rule for when to send a new version,\nbut batching feedback and avoiding multiple rerolls of the same series\nin a single day is a useful default. The text also mentions factors that\nmay affect this, such as the size of the series, the depth of review,\nand whether the topic is close to being picked up.\n\nSince I am the newbie here, please tell me how to attribute the credit\nto Patrick. Thank you Patrick!\n\nPlease feel free to make comments. Thank you.\n\n[1]: \n[2]: \n\n---\n\nChanges in v2:\n\nFor [PATCH 1/2] doc: encourage review replies before rerolling:\n\n - Add \"social interactions\" in commit message.\n\nI didn't do any changes to this version for Patrick's comments in [a]:\n\n> I feel like the new version doesn't really add anything significant to\n> this paragraph that it didn't already say before your patch, but it does\n> so with more words.\n> I'm of course biased though, so maybe more words help newcomers?\n\nThinking about whether to delete/revert or not. Comments welcome.\n\nFor [PATCH 2/2] doc: advise batching patch rerolls:\n\n - Add a trailer to thank Patrick.\n\n Suggestions from Junio:\n\n - Mention that waiting between rerolls gives reviewers across time\n zones a fair chance to participate.\n - Mention that waiting also encourages authors to polish patches\n before sending them.\n\n[a] \n\n---\nbase commit: 700432b2ba (topic flush before -rc1 (batch 1), 2026-06-15)\n\n\nWeijie Yuan (2):\n doc: encourage review replies before rerolling\n doc: advise batching patch rerolls\n\n Documentation/MyFirstContribution.adoc | 32 ++++++++++++++++++++++----\n Documentation/SubmittingPatches | 22 ++++++++++++++----\n 2 files changed, 45 insertions(+), 9 deletions(-)\n\nRange-diff against v1:\n1: b9fa5fe471 ! 1: 4bb1efe71d doc: encourage review replies before rerolling\n @@ Commit message\n \n This makes the author's reasoning explicit before the next version is\n prepared, instead of forcing reviewers to infer it from the rerolled\n - patches.\n + patches. It also encourages more direct social interaction between\n + contributors and helps foster a more collaborative review process.\n \n Signed-off-by: Weijie Yuan \n \n2: fafec6b31d ! 2: 496a08c74d doc: advise batching patch rerolls\n @@ Commit message\n Contributors often need guidance on how quickly to send later iterations\n of a patch series. Add a rough default of no more than one new version\n of the same series per day so feedback can be batched and reviewers have\n - time to comment.\n + time to comment regardless of their time zones.\n \n Mention factors that can affect the timing, such as series size, review\n depth, substantial rework, and how close the topic is to being accepted.\n + Also point out that avoiding rapid rerolls encourages authors to polish\n + each version before sending it, so reviewers can focus on substantial\n + issues.\n \n + Helped-by: Patrick Steinhardt \n Signed-off-by: Weijie Yuan \n \n ## Documentation/MyFirstContribution.adoc ##\n @@ Documentation/MyFirstContribution.adoc: previous one\" patches over 2 days), revi\n single polished version came 2 days later instead, and that version with\n fewer mistakes were the only one they would need to review.\n \n -+This consideration applies not only when going from the initial patch to v2, but\n -+also to later iterations of the same series. There is no fixed rule for how long\n -+to wait before sending a new version. A useful default is to send at most one\n -+new version of the same patch series per day. This gives multiple reviewers time\n -+to comment, lets you batch feedback together, and gives you time to think\n -+through the comments you received.\n ++This consideration applies not only when going from the initial patch to v2,\n ++but also to later iterations of the same series. There is no fixed rule for how\n ++long to wait before sending a new version. A useful default is to send at most\n ++one new version of the same patch series per day. This gives multiple reviewers\n ++time to comment, gives reviewers across time zones a fair chance to\n ++participate, lets you batch feedback together, and gives you time to think\n ++through the comments you received. Knowing that you should not immediately send\n ++another version also encourages you to review the patches more carefully before\n ++sending them, catch small mistakes such as typos and off-by-one errors\n ++yourself, and let reviewers spend more of their attention on design,\n ++algorithms, and other substantial issues.\n +\n +The right timing depends on the topic and the feedback. Larger series usually\n +need more review time. If the only comments so far are minor, such as typo\n @@ Documentation/MyFirstContribution.adoc: previous one\" patches over 2 days), revi\n === Responding to Reviews\n \n ## Documentation/SubmittingPatches ##\n -@@ Documentation/SubmittingPatches: It is often beneficial to allow some time for reviewers to provide\n +@@ Documentation/SubmittingPatches: area.\n + It is often beneficial to allow some time for reviewers to provide\n feedback before sending a new version, rather than sending an updated\n series immediately after receiving a review. This helps collect broader\n - input and avoids unnecessary churn from many rapid iterations.\n +-input and avoids unnecessary churn from many rapid iterations.\n ++input, gives reviewers in different time zones a fair chance to comment,\n ++and avoids unnecessary churn from many rapid iterations. Waiting also\n ++encourages you to polish each version before sending it, so reviewers can\n ++focus on substantial issues rather than typos or other small mistakes.\n ++\n +As a rough default, avoid sending more than one new version of the same\n +series per day, while considering the size of the series, the depth of\n-- \n2.54.0\n\n"},{"id":"545774","messageId":"4bb1efe71da5a9a16860a1fc4d22ef9ceab83ca2.1781714757.git.wy@wyuan.org","threadId":"65803","inReplyTo":"cover.1781714757.git.wy@wyuan.org","subject":"[PATCH v2 1/2] doc: encourage review replies before rerolling","fromName":"Weijie Yuan","fromEmail":"wy@wyuan.org","sentAt":"2026-06-17T16:50:40Z","receivedAt":"2026-06-17T16:50:56Z","isPatch":true,"body":"Review feedback should not be answered only by sending a new patch\nversion. Encourage contributors to discuss their planned response in the\nmailing-list thread before rerolling.\n\nThis makes the author's reasoning explicit before the next version is\nprepared, instead of forcing reviewers to infer it from the rerolled\npatches. It also encourages more direct social interaction between\ncontributors and helps foster a more collaborative review process.\n\nSigned-off-by: Weijie Yuan \n---\n Documentation/MyFirstContribution.adoc | 12 +++++++-----\n Documentation/SubmittingPatches | 12 +++++++++---\n 2 files changed, 16 insertions(+), 8 deletions(-)\n\ndiff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc\nindex b9fdefce02..00704ab91e 100644\n--- a/Documentation/MyFirstContribution.adoc\n+++ b/Documentation/MyFirstContribution.adoc\n@@ -1337,11 +1337,13 @@ fewer mistakes were the only one they would need to review.\n After a few days, you will hopefully receive a reply to your patchset with some\n comments. Woohoo! Now you can get back to work.\n \n-It's good manners to reply to each comment, notifying the reviewer that you have\n-made the change suggested, feel the original is better, or that the comment\n-inspired you to do something a new way which is superior to both the original\n-and the suggested change. This way reviewers don't need to inspect your v2 to\n-figure out whether you implemented their comment or not.\n+It's good manners to reply to each comment in the mailing list discussion\n+instead of letting the next version of your patch be your only response. Tell\n+the reviewer whether you plan to make the suggested change, keep the original,\n+or pursue a different approach. This way reviewers can respond to your reasoning\n+before you spend time preparing a version they may not agree with, and later do\n+not need to inspect your v2 to figure out whether you implemented their comment\n+or not.\n \n Reviewers may ask you about what you wrote in the patchset, either in\n the proposed commit log message or in the changes themselves. You\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex f042bb5aaf..6c1e1f6423 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -48,8 +48,12 @@ area.\n \n . You get comments and suggestions for improvements. You may even get\n them in an \"on top of your change\" patch form. You are expected to\n- respond to them with \"Reply-All\" on the mailing list, while taking\n- them into account while preparing an updated set of patches.\n+ respond to them with \"Reply-All\" on the mailing list, instead of\n+ letting an updated patch series be your only response. Tell\n+ reviewers which suggestions you plan to use, which ones you disagree\n+ with, and when a comment leads you to consider a different approach.\n+ Use these replies and any follow-up discussion as input when\n+ preparing an updated set of patches.\n +\n It is often beneficial to allow some time for reviewers to provide\n feedback before sending a new version, rather than sending an updated\n@@ -613,7 +617,9 @@ grouped into their own e-mail thread to help readers find all parts of the\n series. To that end, send them as replies to either an additional \"cover\n letter\" message (see below), the first patch, or the respective preceding patch.\n Here is a link:MyFirstContribution.html#v2-git-send-email[step-by-step guide] on\n-how to submit updated versions of a patch series.\n+how to submit updated versions of a patch series. Before sending another\n+version, make sure you have answered meaningful review comments in the existing\n+discussion.\n \n If your log message (including your name on the\n `Signed-off-by` trailer) is not writable in ASCII, make sure that\n-- \n2.54.0\n\n"},{"id":"545775","messageId":"496a08c74ddd9368587d032da7117520af1478ae.1781714757.git.wy@wyuan.org","threadId":"65803","inReplyTo":"cover.1781714757.git.wy@wyuan.org","subject":"[PATCH v2 2/2] doc: advise batching patch rerolls","fromName":"Weijie Yuan","fromEmail":"wy@wyuan.org","sentAt":"2026-06-17T16:51:34Z","receivedAt":"2026-06-17T16:51:53Z","isPatch":true,"body":"Contributors often need guidance on how quickly to send later iterations\nof a patch series. Add a rough default of no more than one new version\nof the same series per day so feedback can be batched and reviewers have\ntime to comment regardless of their time zones.\n\nMention factors that can affect the timing, such as series size, review\ndepth, substantial rework, and how close the topic is to being accepted.\nAlso point out that avoiding rapid rerolls encourages authors to polish\neach version before sending it, so reviewers can focus on substantial\nissues.\n\nHelped-by: Patrick Steinhardt \nSigned-off-by: Weijie Yuan \n---\n Documentation/MyFirstContribution.adoc | 20 ++++++++++++++++++++\n Documentation/SubmittingPatches | 12 ++++++++++--\n 2 files changed, 30 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc\nindex 00704ab91e..f8f5f4e320 100644\n--- a/Documentation/MyFirstContribution.adoc\n+++ b/Documentation/MyFirstContribution.adoc\n@@ -1330,6 +1330,26 @@ previous one\" patches over 2 days), reviewers would strongly prefer if a\n single polished version came 2 days later instead, and that version with\n fewer mistakes were the only one they would need to review.\n \n+This consideration applies not only when going from the initial patch to v2,\n+but also to later iterations of the same series. There is no fixed rule for how\n+long to wait before sending a new version. A useful default is to send at most\n+one new version of the same patch series per day. This gives multiple reviewers\n+time to comment, gives reviewers across time zones a fair chance to\n+participate, lets you batch feedback together, and gives you time to think\n+through the comments you received. Knowing that you should not immediately send\n+another version also encourages you to review the patches more carefully before\n+sending them, catch small mistakes such as typos and off-by-one errors\n+yourself, and let reviewers spend more of their attention on design,\n+algorithms, and other substantial issues.\n+\n+The right timing depends on the topic and the feedback. Larger series usually\n+need more review time. If the only comments so far are minor, such as typo\n+fixes, it often makes sense to wait a little longer in case deeper reviews are\n+still coming. If the comments require substantial rework, sending a new version\n+sooner may save reviewers from spending time on a version you already know will\n+change significantly. If the topic is close to being accepted and the remaining\n+comments are small, a quicker new version may also be fine.\n+\n \n [[reviewing]]\n === Responding to Reviews\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex 6c1e1f6423..13f180a8bd 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -58,7 +58,14 @@ area.\n It is often beneficial to allow some time for reviewers to provide\n feedback before sending a new version, rather than sending an updated\n series immediately after receiving a review. This helps collect broader\n-input and avoids unnecessary churn from many rapid iterations.\n+input, gives reviewers in different time zones a fair chance to comment,\n+and avoids unnecessary churn from many rapid iterations. Waiting also\n+encourages you to polish each version before sending it, so reviewers can\n+focus on substantial issues rather than typos or other small mistakes.\n++\n+As a rough default, avoid sending more than one new version of the same\n+series per day, while considering the size of the series, the depth of\n+review, and how close the topic is to being accepted.\n \n . These early update iterations are expected to be full replacements,\n not incremental updates on top of what you posted already. If you\n@@ -619,7 +626,8 @@ letter\" message (see below), the first patch, or the respective preceding patch.\n Here is a link:MyFirstContribution.html#v2-git-send-email[step-by-step guide] on\n how to submit updated versions of a patch series. Before sending another\n version, make sure you have answered meaningful review comments in the existing\n-discussion.\n+discussion. Also give reviewers enough time to comment before sending another\n+version.\n \n If your log message (including your name on the\n `Signed-off-by` trailer) is not writable in ASCII, make sure that\n-- \n2.54.0\n\n"},{"id":"545785","messageId":"xmqq4ij1vywy.fsf@gitster.g","threadId":"65803","inReplyTo":"496a08c74ddd9368587d032da7117520af1478ae.1781714757.git.wy@wyuan.org","subject":"Re: [PATCH v2 2/2] doc: advise batching patch rerolls","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-06-17T17:50:53Z","receivedAt":"2026-06-17T17:50:55Z","isPatch":true,"body":"Weijie Yuan writes:\n\n> +The right timing depends on the topic and the feedback. Larger series usually\n> +need more review time. If the only comments so far are minor, such as typo\n> +fixes, it often makes sense to wait a little longer in case deeper reviews are\n> +still coming.\n\nAll sensible up to this point.\n\n> If the comments require substantial rework, sending a new version\n> +sooner may save reviewers from spending time on a version you already know will\n> +change significantly.\n\nI am not sure about this one. Even though the intention to avoid\nwasting reviewers' time spent on reading through the previous\nversion that will be invalidated is a good one, by definition, a\nsubstantial rework will naturally take time, and it is better not to\nrush and send an updated version with substantial changes that you\nyourself haven't had a chance to thoroughly review yet.\n\nIn such a case, it would be a better idea to respond to the review\nthat made you realize a substantial rewrite is needed with a simple\n\"I'll make a substantial rework based on this comment, which would\ninvalidate this and that part of the current patch series, so please\ndo not waste reviewer cycles on these parts until I send an updated\nseries out\" message.\n\n> If the topic is close to being accepted and the remaining\n> +comments are small, a quicker new version may also be fine.\n\nI am not sure if this needs to be codified.\n\nI often see (e.g., in patches from Patrick) that an iteration is\nmarked clearly as final candidate that the author is not aware of\nany outstanding issues. This encourages reviewers to ask \"what\nabout this one raised there?\" to remind what is missed, or chime in\nwith \"yup, this looks good\" to show support. Such a note is highly\nrecommended, but I do not see a need to say \"the (supposedly) final\none is specifically allowed to be sent without waiting\" even then.\n\nThanks.\n\n\n\n\n"},{"id":"545951","messageId":"ajVCD51lLvHreyJB@wyuan.org","threadId":"65803","inReplyTo":"xmqq4ij1vywy.fsf@gitster.g","subject":"Re: [PATCH v2 2/2] doc: advise batching patch rerolls","fromName":"Weijie Yuan","fromEmail":"wy@wyuan.org","sentAt":"2026-06-19T13:20:15Z","receivedAt":"2026-06-19T13:20:32Z","isPatch":true,"body":"Sorry for the late reply. I spent some time looking back through the\ndiscussions on earlier patch series, to check my patch itself, of course\nbecause I'm apparently a newcomer here.\n\nOn Wed, Jun 17, 2026 at 10:50:53AM -0700, Junio C Hamano wrote:\n> > If the comments require substantial rework, sending a new version\n> > +sooner may save reviewers from spending time on a version you already know will\n> > +change significantly.\n> \n> I am not sure about this one. Even though the intention to avoid\n> wasting reviewers' time spent on reading through the previous\n> version that will be invalidated is a good one, by definition, a\n> substantial rework will naturally take time, and it is better not to\n> rush and send an updated version with substantial changes that you\n> yourself haven't had a chance to thoroughly review yet.\n> \n> In such a case, it would be a better idea to respond to the review\n> that made you realize a substantial rewrite is needed with a simple\n> \"I'll make a substantial rework based on this comment, which would\n> invalidate this and that part of the current patch series, so please\n> do not waste reviewer cycles on these parts until I send an updated\n> series out\" message.\n\nI think the approach you recommended is obviously more reasonable.\n\nIt would be better to give everyone a heads-up \"I am working on a\nnew version.\"\n\nI will improve this part accordingly.\n\n> > If the topic is close to being accepted and the remaining\n> > +comments are small, a quicker new version may also be fine.\n> \n> I am not sure if this needs to be codified.\n> \n> I often see (e.g., in patches from Patrick) that an iteration is\n> marked clearly as final candidate that the author is not aware of\n> any outstanding issues. This encourages reviewers to ask \"what\n> about this one raised there?\" to remind what is missed, or chime in\n> with \"yup, this looks good\" to show support. Such a note is highly\n> recommended, but I do not see a need to say \"the (supposedly) final\n> one is specifically allowed to be sent without waiting\" even then.\n\nActually I thought Patrick would say something here ;-) so I waited a\nfew more days to see whether anyone else had any suggestions.\n\nBut here I think Patrick's original intention is: If your series is\n*close* to be accepted, (while I'm not sure what the precise definition\nof this \"close to be accepted\", does it means: commented by Junio with\n\"Looks good\", or reviewed by the community/core contributors with \"Makes\nsense\"?) and this time there happens to be a small issue, you can\nre-roll quickly to make your series more \"sturdy\" to wait for\nmaintainer's final examination and further merges.\n\nSo, I think the situation you are describing here is that this version\nof the patch has already been declared by the *author* to be the final\nversion. (i.e. waiting for Junio to do the last exam)\n\nTherefore, I do not think the two situations conflict with each other,\nor are directly related. One concerns a patch that is already close to\nreceiving the maintainer's final verdict, where a minor issue is\ndiscovered and the author quickly rerolls it. The other concerns an\nauthor who, without realizing that some issues remain unresolved, rushes\nto send what they believe to be the final version and then waits for the\nmaintainer to review it.\n\nFor the latter case, I think it would be better to add a sentence along\nthe lines of: \"Before sending a new version/the final version, check\nonce more whether there are any unresolved issues,\" if the existing\ndocumentation does not already make this clear.\n\nThat said, I am not familiar with how patch discussions have played out\nin the past, so please directly point out any mistakes in my\nunderstanding. I have to admit that, by this point in writing the\nmessage, I have become a little tangled up in my own reasoning.\n\nThanks!\n"},{"id":"546066","messageId":"cover.1782028813.git.wy@wyuan.org","threadId":"65803","inReplyTo":"cover.1781714757.git.wy@wyuan.org","subject":"[PATCH v3 0/2] doc: clarify review replies and reroll timing","fromName":"Weijie Yuan","fromEmail":"wy@wyuan.org","sentAt":"2026-06-21T08:04:36Z","receivedAt":"2026-06-21T08:05:01Z","isPatch":true,"body":"This small series updates the 2 documentations: MyFirstContribution and\nSubmittingPatches.\n\nThe first patch clarifies that review feedback should not be answered\nonly by sending a new version of the patches, which is talked in [1].\nContributors are encouraged to and should discuss their planned response in\nthe existing review thread, so that the next version does not become the\nonly place where reviewers can infer the author's reasoning.\n\nThe second patch is originally from an email from Patrick [2], which\ndocuments a rough expectation around reroll frequency.\n\nPatrick suggests: There is no hard rule for when to send a new version,\nbut batching feedback and avoiding multiple rerolls of the same series\nin a single day is a useful default. The text also mentions factors that\nmay affect this, such as the size of the series, the depth of review,\nand whether the topic is close to being picked up.\n(Edit: the last point is discussed by Junio[3], which is improved in v3)\n\nSince I am the newbie here, please tell me how to attribute the credit\nto Patrick. Thank you Patrick!\n(Edit: finished with the Helped-by trailer in v2)\n\n[1]: \n[2]: \n[3]: \n\n---\nChanges in v3:\n\n - Reworked the substantial-rework case. Instead of suggesting that\n authors send a new version sooner, the text now advises authors not\n to rush out an updated version before reviewing the larger changes\n carefully. It recommends replying to the review that prompted the\n rewrite, saying that a substantial rework is planned, and pointing\n out which parts of the current series will become obsolete.\n\n - Dropped the advice that a topic close to being accepted may justify\n a quicker reroll.\n\n - Removed \"how close the topic is to being accepted\" from the short\n reroll-timing guidance in Documentation/SubmittingPatches.\n\n - Updated the commit message of patch 2 accordingly.\n\n\nChanges in v2:\n\nFor [PATCH 1/2] doc: encourage review replies before rerolling:\n\n - Add \"social interactions\" in commit message.\n\n I didn't do any changes for Patrick's comments in [a]:\n\n > I feel like the new version doesn't really add anything significant\n > to this paragraph that it didn't already say before your patch, but\n > it does so with more words.\n > I'm of course biased though, so maybe more words help newcomers?\n\n Thinking about whether to delete/revert or not. Comments welcome.\n\nFor [PATCH 2/2] doc: advise batching patch rerolls:\n\n - Add a trailer to thank Patrick.\n\n Suggestions from Junio:\n\n - Mention that waiting between rerolls gives reviewers across time\n zones a fair chance to participate.\n - Mention that waiting also encourages authors to polish patches\n before sending them.\n\n[a] \n---\nbase commit: 700432b2ba (topic flush before -rc1 (batch 1), 2026-06-15)\n\nWeijie Yuan (2):\n doc: encourage review replies before rerolling\n doc: advise batching patch rerolls\n\n Documentation/MyFirstContribution.adoc | 34 ++++++++++++++++++++++----\n Documentation/SubmittingPatches | 23 ++++++++++++++---\n 2 files changed, 48 insertions(+), 9 deletions(-)\n\nRange-diff against v2:\n1: 4bb1efe71d = 1: 4bb1efe71d doc: encourage review replies before rerolling\n2: 496a08c74d ! 2: e1050a6ef5 doc: advise batching patch rerolls\n @@ Commit message\n time to comment regardless of their time zones.\n \n Mention factors that can affect the timing, such as series size, review\n - depth, substantial rework, and how close the topic is to being accepted.\n - Also point out that avoiding rapid rerolls encourages authors to polish\n - each version before sending it, so reviewers can focus on substantial\n - issues.\n + depth, and substantial rework. Also point out that avoiding rapid\n + rerolls encourages authors to polish each version before sending it, so\n + reviewers can focus on substantial issues.\n \n Helped-by: Patrick Steinhardt \n Signed-off-by: Weijie Yuan \n @@ Documentation/MyFirstContribution.adoc: previous one\" patches over 2 days), revi\n +The right timing depends on the topic and the feedback. Larger series usually\n +need more review time. If the only comments so far are minor, such as typo\n +fixes, it often makes sense to wait a little longer in case deeper reviews are\n -+still coming. If the comments require substantial rework, sending a new version\n -+sooner may save reviewers from spending time on a version you already know will\n -+change significantly. If the topic is close to being accepted and the remaining\n -+comments are small, a quicker new version may also be fine.\n ++still coming. If the comments call for substantial rework, do not rush out an\n ++updated version before you have reviewed the larger changes carefully. Instead,\n ++reply to the review that prompted the rewrite, say that you are preparing a\n ++substantial rework, and mention which parts of the current series will become\n ++obsolete so reviewers can avoid spending time on them until the updated series\n ++is ready.\n +\n \n [[reviewing]]\n @@ Documentation/SubmittingPatches: area.\n -input and avoids unnecessary churn from many rapid iterations.\n +input, gives reviewers in different time zones a fair chance to comment,\n +and avoids unnecessary churn from many rapid iterations. Waiting also\n -+encourages you to polish each version before sending it, so reviewers can\n -+focus on substantial issues rather than typos or other small mistakes.\n ++encourages you to polish each version before sending it, so reviewers\n ++can focus on substantial issues rather than typos or other small\n ++mistakes. (only changes textwidth here)\n ++\n +As a rough default, avoid sending more than one new version of the same\n -+series per day, while considering the size of the series, the depth of\n -+review, and how close the topic is to being accepted.\n ++series per day, while considering the size of the series and the depth\n ++of review.\n \n . These early update iterations are expected to be full replacements,\n not incremental updates on top of what you posted already. If you\n-- \n2.54.0\n\n"},{"id":"546067","messageId":"4bb1efe71da5a9a16860a1fc4d22ef9ceab83ca2.1782028813.git.wy@wyuan.org","threadId":"65803","inReplyTo":"cover.1782028813.git.wy@wyuan.org","subject":"[PATCH v3 1/2] doc: encourage review replies before rerolling","fromName":"Weijie Yuan","fromEmail":"wy@wyuan.org","sentAt":"2026-06-21T08:05:06Z","receivedAt":"2026-06-21T08:05:26Z","isPatch":true,"body":"Review feedback should not be answered only by sending a new patch\nversion. Encourage contributors to discuss their planned response in the\nmailing-list thread before rerolling.\n\nThis makes the author's reasoning explicit before the next version is\nprepared, instead of forcing reviewers to infer it from the rerolled\npatches. It also encourages more direct social interaction between\ncontributors and helps foster a more collaborative review process.\n\nSigned-off-by: Weijie Yuan \n---\n Documentation/MyFirstContribution.adoc | 12 +++++++-----\n Documentation/SubmittingPatches | 12 +++++++++---\n 2 files changed, 16 insertions(+), 8 deletions(-)\n\ndiff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc\nindex b9fdefce02..00704ab91e 100644\n--- a/Documentation/MyFirstContribution.adoc\n+++ b/Documentation/MyFirstContribution.adoc\n@@ -1337,11 +1337,13 @@ fewer mistakes were the only one they would need to review.\n After a few days, you will hopefully receive a reply to your patchset with some\n comments. Woohoo! Now you can get back to work.\n \n-It's good manners to reply to each comment, notifying the reviewer that you have\n-made the change suggested, feel the original is better, or that the comment\n-inspired you to do something a new way which is superior to both the original\n-and the suggested change. This way reviewers don't need to inspect your v2 to\n-figure out whether you implemented their comment or not.\n+It's good manners to reply to each comment in the mailing list discussion\n+instead of letting the next version of your patch be your only response. Tell\n+the reviewer whether you plan to make the suggested change, keep the original,\n+or pursue a different approach. This way reviewers can respond to your reasoning\n+before you spend time preparing a version they may not agree with, and later do\n+not need to inspect your v2 to figure out whether you implemented their comment\n+or not.\n \n Reviewers may ask you about what you wrote in the patchset, either in\n the proposed commit log message or in the changes themselves. You\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex f042bb5aaf..6c1e1f6423 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -48,8 +48,12 @@ area.\n \n . You get comments and suggestions for improvements. You may even get\n them in an \"on top of your change\" patch form. You are expected to\n- respond to them with \"Reply-All\" on the mailing list, while taking\n- them into account while preparing an updated set of patches.\n+ respond to them with \"Reply-All\" on the mailing list, instead of\n+ letting an updated patch series be your only response. Tell\n+ reviewers which suggestions you plan to use, which ones you disagree\n+ with, and when a comment leads you to consider a different approach.\n+ Use these replies and any follow-up discussion as input when\n+ preparing an updated set of patches.\n +\n It is often beneficial to allow some time for reviewers to provide\n feedback before sending a new version, rather than sending an updated\n@@ -613,7 +617,9 @@ grouped into their own e-mail thread to help readers find all parts of the\n series. To that end, send them as replies to either an additional \"cover\n letter\" message (see below), the first patch, or the respective preceding patch.\n Here is a link:MyFirstContribution.html#v2-git-send-email[step-by-step guide] on\n-how to submit updated versions of a patch series.\n+how to submit updated versions of a patch series. Before sending another\n+version, make sure you have answered meaningful review comments in the existing\n+discussion.\n \n If your log message (including your name on the\n `Signed-off-by` trailer) is not writable in ASCII, make sure that\n-- \n2.54.0\n\n"},{"id":"546068","messageId":"e1050a6ef5e26299b2c6d9743067fe3d7f4f8071.1782028813.git.wy@wyuan.org","threadId":"65803","inReplyTo":"cover.1782028813.git.wy@wyuan.org","subject":"[PATCH v3 2/2] doc: advise batching patch rerolls","fromName":"Weijie Yuan","fromEmail":"wy@wyuan.org","sentAt":"2026-06-21T08:05:34Z","receivedAt":"2026-06-21T08:05:51Z","isPatch":true,"body":"Contributors often need guidance on how quickly to send later iterations\nof a patch series. Add a rough default of no more than one new version\nof the same series per day so feedback can be batched and reviewers have\ntime to comment regardless of their time zones.\n\nMention factors that can affect the timing, such as series size, review\ndepth, and substantial rework. Also point out that avoiding rapid\nrerolls encourages authors to polish each version before sending it, so\nreviewers can focus on substantial issues.\n\nHelped-by: Patrick Steinhardt \nSigned-off-by: Weijie Yuan \n---\n Documentation/MyFirstContribution.adoc | 22 ++++++++++++++++++++++\n Documentation/SubmittingPatches | 13 +++++++++++--\n 2 files changed, 33 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc\nindex 00704ab91e..35105bc3b4 100644\n--- a/Documentation/MyFirstContribution.adoc\n+++ b/Documentation/MyFirstContribution.adoc\n@@ -1330,6 +1330,28 @@ previous one\" patches over 2 days), reviewers would strongly prefer if a\n single polished version came 2 days later instead, and that version with\n fewer mistakes were the only one they would need to review.\n \n+This consideration applies not only when going from the initial patch to v2,\n+but also to later iterations of the same series. There is no fixed rule for how\n+long to wait before sending a new version. A useful default is to send at most\n+one new version of the same patch series per day. This gives multiple reviewers\n+time to comment, gives reviewers across time zones a fair chance to\n+participate, lets you batch feedback together, and gives you time to think\n+through the comments you received. Knowing that you should not immediately send\n+another version also encourages you to review the patches more carefully before\n+sending them, catch small mistakes such as typos and off-by-one errors\n+yourself, and let reviewers spend more of their attention on design,\n+algorithms, and other substantial issues.\n+\n+The right timing depends on the topic and the feedback. Larger series usually\n+need more review time. If the only comments so far are minor, such as typo\n+fixes, it often makes sense to wait a little longer in case deeper reviews are\n+still coming. If the comments call for substantial rework, do not rush out an\n+updated version before you have reviewed the larger changes carefully. Instead,\n+reply to the review that prompted the rewrite, say that you are preparing a\n+substantial rework, and mention which parts of the current series will become\n+obsolete so reviewers can avoid spending time on them until the updated series\n+is ready.\n+\n \n [[reviewing]]\n === Responding to Reviews\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex 6c1e1f6423..d89efe0707 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -58,7 +58,15 @@ area.\n It is often beneficial to allow some time for reviewers to provide\n feedback before sending a new version, rather than sending an updated\n series immediately after receiving a review. This helps collect broader\n-input and avoids unnecessary churn from many rapid iterations.\n+input, gives reviewers in different time zones a fair chance to comment,\n+and avoids unnecessary churn from many rapid iterations. Waiting also\n+encourages you to polish each version before sending it, so reviewers\n+can focus on substantial issues rather than typos or other small\n+mistakes.\n++\n+As a rough default, avoid sending more than one new version of the same\n+series per day, while considering the size of the series and the depth\n+of review.\n \n . These early update iterations are expected to be full replacements,\n not incremental updates on top of what you posted already. If you\n@@ -619,7 +627,8 @@ letter\" message (see below), the first patch, or the respective preceding patch.\n Here is a link:MyFirstContribution.html#v2-git-send-email[step-by-step guide] on\n how to submit updated versions of a patch series. Before sending another\n version, make sure you have answered meaningful review comments in the existing\n-discussion.\n+discussion. Also give reviewers enough time to comment before sending another\n+version.\n \n If your log message (including your name on the\n `Signed-off-by` trailer) is not writable in ASCII, make sure that\n-- \n2.54.0\n\n"},{"id":"546296","messageId":"ajvDrjk-bTvYaQtU@pks.im","threadId":"65803","inReplyTo":"ajVCD51lLvHreyJB@wyuan.org","subject":"Re: [PATCH v2 2/2] doc: advise batching patch rerolls","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-06-24T11:46:54Z","receivedAt":"2026-06-24T11:47:01Z","isPatch":true,"body":"On Fri, Jun 19, 2026 at 09:20:15PM +0800, Weijie Yuan wrote:\n> Sorry for the late reply. I spent some time looking back through the\n> discussions on earlier patch series, to check my patch itself, of course\n> because I'm apparently a newcomer here.\n> \n> On Wed, Jun 17, 2026 at 10:50:53AM -0700, Junio C Hamano wrote:\n> > > If the comments require substantial rework, sending a new version\n> > > +sooner may save reviewers from spending time on a version you already know will\n> > > +change significantly.\n> > \n> > I am not sure about this one. Even though the intention to avoid\n> > wasting reviewers' time spent on reading through the previous\n> > version that will be invalidated is a good one, by definition, a\n> > substantial rework will naturally take time, and it is better not to\n> > rush and send an updated version with substantial changes that you\n> > yourself haven't had a chance to thoroughly review yet.\n> > \n> > In such a case, it would be a better idea to respond to the review\n> > that made you realize a substantial rewrite is needed with a simple\n> > \"I'll make a substantial rework based on this comment, which would\n> > invalidate this and that part of the current patch series, so please\n> > do not waste reviewer cycles on these parts until I send an updated\n> > series out\" message.\n> \n> I think the approach you recommended is obviously more reasonable.\n> \n> It would be better to give everyone a heads-up \"I am working on a\n> new version.\"\n> \n> I will improve this part accordingly.\n\nYeah, that works for me, as well.\n\n> > > If the topic is close to being accepted and the remaining\n> > > +comments are small, a quicker new version may also be fine.\n> > \n> > I am not sure if this needs to be codified.\n> > \n> > I often see (e.g., in patches from Patrick) that an iteration is\n> > marked clearly as final candidate that the author is not aware of\n> > any outstanding issues. This encourages reviewers to ask \"what\n> > about this one raised there?\" to remind what is missed, or chime in\n> > with \"yup, this looks good\" to show support. Such a note is highly\n> > recommended, but I do not see a need to say \"the (supposedly) final\n> > one is specifically allowed to be sent without waiting\" even then.\n> \n> Actually I thought Patrick would say something here ;-) so I waited a\n> few more days to see whether anyone else had any suggestions.\n> \n> But here I think Patrick's original intention is: If your series is\n> *close* to be accepted, (while I'm not sure what the precise definition\n> of this \"close to be accepted\", does it means: commented by Junio with\n> \"Looks good\", or reviewed by the community/core contributors with \"Makes\n> sense\"?) and this time there happens to be a small issue, you can\n> re-roll quickly to make your series more \"sturdy\" to wait for\n> maintainer's final examination and further merges.\n> \n> So, I think the situation you are describing here is that this version\n> of the patch has already been declared by the *author* to be the final\n> version. (i.e. waiting for Junio to do the last exam)\n\nMy \"close to be accepted\" feeling is when you've had multiple rounds of\ndesign discussions already, everyone is on the same page, and all you\ngot on the last review round is a couple of typo fixes.\n\nBut all of this is highly subjective, so it'll always depend and it\nwon't be easy to codify all of that. Nor is that necessary, I guess. We\nreally only want to provide some rough guidance.\n\n> Therefore, I do not think the two situations conflict with each other,\n> or are directly related. One concerns a patch that is already close to\n> receiving the maintainer's final verdict, where a minor issue is\n> discovered and the author quickly rerolls it. The other concerns an\n> author who, without realizing that some issues remain unresolved, rushes\n> to send what they believe to be the final version and then waits for the\n> maintainer to review it.\n> \n> For the latter case, I think it would be better to add a sentence along\n> the lines of: \"Before sending a new version/the final version, check\n> once more whether there are any unresolved issues,\" if the existing\n> documentation does not already make this clear.\n\nI think that should mostly be clear with our documentation. And\neventually, we should also expect people to have some common sense :)\n\n> That said, I am not familiar with how patch discussions have played out\n> in the past, so please directly point out any mistakes in my\n> understanding. I have to admit that, by this point in writing the\n> message, I have become a little tangled up in my own reasoning.\n\nI guess that's kind of expected, mostly because many of these things are\nhighly subjective and will depend on the situation. The guidance does\nnot have to be perfect, you'll probably be able to find counterexamples\nfor many of the cases.\n\nPatrick\n"},{"id":"546297","messageId":"ajvDsy1qVCZoqiCu@pks.im","threadId":"65803","inReplyTo":"e1050a6ef5e26299b2c6d9743067fe3d7f4f8071.1782028813.git.wy@wyuan.org","subject":"Re: [PATCH v3 2/2] doc: advise batching patch rerolls","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-06-24T11:46:59Z","receivedAt":"2026-06-24T11:47:04Z","isPatch":true,"body":"On Sun, Jun 21, 2026 at 04:05:34PM +0800, Weijie Yuan wrote:\n> diff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc\n> index 00704ab91e..35105bc3b4 100644\n> --- a/Documentation/MyFirstContribution.adoc\n> +++ b/Documentation/MyFirstContribution.adoc\n> @@ -1330,6 +1330,28 @@ previous one\" patches over 2 days), reviewers would strongly prefer if a\n> single polished version came 2 days later instead, and that version with\n> fewer mistakes were the only one they would need to review.\n> \n> +This consideration applies not only when going from the initial patch to v2,\n> +but also to later iterations of the same series. There is no fixed rule for how\n> +long to wait before sending a new version. A useful default is to send at most\n> +one new version of the same patch series per day. This gives multiple reviewers\n> +time to comment, gives reviewers across time zones a fair chance to\n> +participate, lets you batch feedback together, and gives you time to think\n> +through the comments you received. Knowing that you should not immediately send\n> +another version also encourages you to review the patches more carefully before\n> +sending them, catch small mistakes such as typos and off-by-one errors\n> +yourself, and let reviewers spend more of their attention on design,\n> +algorithms, and other substantial issues.\n> +\n> +The right timing depends on the topic and the feedback. Larger series usually\n> +need more review time. If the only comments so far are minor, such as typo\n> +fixes, it often makes sense to wait a little longer in case deeper reviews are\n> +still coming. If the comments call for substantial rework, do not rush out an\n> +updated version before you have reviewed the larger changes carefully. Instead,\n> +reply to the review that prompted the rewrite, say that you are preparing a\n> +substantial rework, and mention which parts of the current series will become\n> +obsolete so reviewers can avoid spending time on them until the updated series\n> +is ready.\n\nMakes sense.\n\nPatrick\n"},{"id":"546298","messageId":"ajvDuUiDsmyf5LnX@pks.im","threadId":"65803","inReplyTo":"cover.1782028813.git.wy@wyuan.org","subject":"Re: [PATCH v3 0/2] doc: clarify review replies and reroll timing","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-06-24T11:47:05Z","receivedAt":"2026-06-24T11:47:09Z","isPatch":true,"body":"On Sun, Jun 21, 2026 at 04:04:36PM +0800, Weijie Yuan wrote:\n> Changes in v3:\n> \n> - Reworked the substantial-rework case. Instead of suggesting that\n> authors send a new version sooner, the text now advises authors not\n> to rush out an updated version before reviewing the larger changes\n> carefully. It recommends replying to the review that prompted the\n> rewrite, saying that a substantial rework is planned, and pointing\n> out which parts of the current series will become obsolete.\n> \n> - Dropped the advice that a topic close to being accepted may justify\n> a quicker reroll.\n> \n> - Removed \"how close the topic is to being accepted\" from the short\n> reroll-timing guidance in Documentation/SubmittingPatches.\n> \n> - Updated the commit message of patch 2 accordingly.\n\nI'm happy with this version, thanks!\n\nPatrick\n"},{"id":"546379","messageId":"ajzQdgkjGi4y3M0v@wyuan.org","threadId":"65803","inReplyTo":"ajvDrjk-bTvYaQtU@pks.im","subject":"Re: [PATCH v2 2/2] doc: advise batching patch rerolls","fromName":"Weijie Yuan","fromEmail":"wy@wyuan.org","sentAt":"2026-06-25T06:53:42Z","receivedAt":"2026-06-25T06:53:51Z","isPatch":true,"body":"On Wed, Jun 24, 2026 at 01:46:54PM +0200, Patrick Steinhardt wrote:\n> > But here I think Patrick's original intention is: If your series is\n> > *close* to be accepted, (while I'm not sure what the precise definition\n> > of this \"close to be accepted\", does it means: commented by Junio with\n> > \"Looks good\", or reviewed by the community/core contributors with \"Makes\n> > sense\"?) and this time there happens to be a small issue, you can\n> > re-roll quickly to make your series more \"sturdy\" to wait for\n> > maintainer's final examination and further merges.\n> > \n> > So, I think the situation you are describing here is that this version\n> > of the patch has already been declared by the *author* to be the final\n> > version. (i.e. waiting for Junio to do the last exam)\n> \n> My \"close to be accepted\" feeling is when you've had multiple rounds of\n> design discussions already, everyone is on the same page, and all you\n> got on the last review round is a couple of typo fixes.\n> \n> But all of this is highly subjective, so it'll always depend and it\n> won't be easy to codify all of that. Nor is that necessary, I guess. We\n> really only want to provide some rough guidance.\n\nAgreed, thanks!\n\n> > Therefore, I do not think the two situations conflict with each other,\n> > or are directly related. One concerns a patch that is already close to\n> > receiving the maintainer's final verdict, where a minor issue is\n> > discovered and the author quickly rerolls it. The other concerns an\n> > author who, without realizing that some issues remain unresolved, rushes\n> > to send what they believe to be the final version and then waits for the\n> > maintainer to review it.\n> > \n> > For the latter case, I think it would be better to add a sentence along\n> > the lines of: \"Before sending a new version/the final version, check\n> > once more whether there are any unresolved issues,\" if the existing\n> > documentation does not already make this clear.\n> \n> I think that should mostly be clear with our documentation. And\n> eventually, we should also expect people to have some common sense :)\n\nAgreed.\n\n> > That said, I am not familiar with how patch discussions have played out\n> > in the past, so please directly point out any mistakes in my\n> > understanding. I have to admit that, by this point in writing the\n> > message, I have become a little tangled up in my own reasoning.\n> \n> I guess that's kind of expected, mostly because many of these things are\n> highly subjective and will depend on the situation. The guidance does\n> not have to be perfect, you'll probably be able to find counterexamples\n> for many of the cases.\n\nYes, setting the rules too strictly may actually reduce flexibility of\nour project.\n\nThanks!\n"},{"id":"546380","messageId":"ajzQwzimL22iPzAN@wyuan.org","threadId":"65803","inReplyTo":"ajvDuUiDsmyf5LnX@pks.im","subject":"Re: [PATCH v3 0/2] doc: clarify review replies and reroll timing","fromName":"Weijie Yuan","fromEmail":"wy@wyuan.org","sentAt":"2026-06-25T06:54:59Z","receivedAt":"2026-06-25T06:55:08Z","isPatch":true,"body":"On Wed, Jun 24, 2026 at 01:47:05PM +0200, Patrick Steinhardt wrote:\n> On Sun, Jun 21, 2026 at 04:04:36PM +0800, Weijie Yuan wrote:\n> > Changes in v3:\n> > \n> > - Reworked the substantial-rework case. Instead of suggesting that\n> > authors send a new version sooner, the text now advises authors not\n> > to rush out an updated version before reviewing the larger changes\n> > carefully. It recommends replying to the review that prompted the\n> > rewrite, saying that a substantial rework is planned, and pointing\n> > out which parts of the current series will become obsolete.\n> > \n> > - Dropped the advice that a topic close to being accepted may justify\n> > a quicker reroll.\n> > \n> > - Removed \"how close the topic is to being accepted\" from the short\n> > reroll-timing guidance in Documentation/SubmittingPatches.\n> > \n> > - Updated the commit message of patch 2 accordingly.\n> \n> I'm happy with this version, thanks!\n> \n> Patrick\n\nThank you very much for your review and guidance!\n"}]}