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

[Patrick Steinhardt <ps@pks.im>]

On Fri, Jun 19, 2026 at 09:20:15PM +0800, Weijie Yuan wrote:
> Sorry for the late reply. I spent some time looking back through the
> discussions on earlier patch series, to check my patch itself, of course
> because I'm apparently a newcomer here.
> 
> On Wed, Jun 17, 2026 at 10:50:53AM -0700, Junio C Hamano wrote:
> > > 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.
> > 
> > I am not sure about this one.  Even though the intention to avoid
> > wasting reviewers' time spent on reading through the previous
> > version that will be invalidated is a good one, by definition, a
> > substantial rework will naturally take time, and it is better not to
> > rush and send an updated version with substantial changes that you
> > yourself haven't had a chance to thoroughly review yet.
> > 
> > In such a case, it would be a better idea to respond to the review
> > that made you realize a substantial rewrite is needed with a simple
> > "I'll make a substantial rework based on this comment, which would
> > invalidate this and that part of the current patch series, so please
> > do not waste reviewer cycles on these parts until I send an updated
> > series out" message.
> 
> I think the approach you recommended is obviously more reasonable.
> 
> It would be better to give everyone a heads-up "I am working on a
> new version."
> 
> I will improve this part accordingly.

Yeah, that works for me, as well.

> > > If the topic is close to being accepted and the remaining
> > > +comments are small, a quicker new version may also be fine.
> > 
> > I am not sure if this needs to be codified.
> > 
> > I often see (e.g., in patches from Patrick) that an iteration is
> > marked clearly as final candidate that the author is not aware of
> > any outstanding issues.  This encourages reviewers to ask "what
> > about this one raised there?"  to remind what is missed, or chime in
> > with "yup, this looks good" to show support.  Such a note is highly
> > recommended, but I do not see a need to say "the (supposedly) final
> > one is specifically allowed to be sent without waiting" even then.
> 
> Actually I thought Patrick would say something here ;-) so I waited a
> few more days to see whether anyone else had any suggestions.
> 
> But here I think Patrick's original intention is: If your series is
> *close* to be accepted, (while I'm not sure what the precise definition
> of this "close to be accepted", does it means: commented by Junio with
> "Looks good", or reviewed by the community/core contributors with "Makes
> sense"?) and this time there happens to be a small issue, you can
> re-roll quickly to make your series more "sturdy" to wait for
> maintainer's final examination and further merges.
> 
> So, I think the situation you are describing here is that this version
> of the patch has already been declared by the *author* to be the final
> version. (i.e. waiting for Junio to do the last exam)

My "close to be accepted" feeling is when you've had multiple rounds of
design discussions already, everyone is on the same page, and all you
got on the last review round is a couple of typo fixes.

But all of this is highly subjective, so it'll always depend and it
won't be easy to codify all of that. Nor is that necessary, I guess. We
really only want to provide some rough guidance.

> Therefore, I do not think the two situations conflict with each other,
> or are directly related. One concerns a patch that is already close to
> receiving the maintainer's final verdict, where a minor issue is
> discovered and the author quickly rerolls it. The other concerns an
> author who, without realizing that some issues remain unresolved, rushes
> to send what they believe to be the final version and then waits for the
> maintainer to review it.
> 
> For the latter case, I think it would be better to add a sentence along
> the lines of: "Before sending a new version/the final version, check
> once more whether there are any unresolved issues," if the existing
> documentation does not already make this clear.

I think that should mostly be clear with our documentation. And
eventually, we should also expect people to have some common sense :)

> That said, I am not familiar with how patch discussions have played out
> in the past, so please directly point out any mistakes in my
> understanding. I have to admit that, by this point in writing the
> message, I have become a little tangled up in my own reasoning.

I guess that's kind of expected, mostly because many of these things are
highly subjective and will depend on the situation. The guidance does
not have to be perfect, you'll probably be able to find counterexamples
for many of the cases.

Patrick