From: Patrick Steinhardt Date: Tue, 20 Oct 2026 14:33:41 GMT Subject: Re: [PATCH] MyFirstContribution: move preparation of v2 after review discussion Message-ID: In-Reply-To: On Mon, Oct 19, 2026 at 01:43:48PM -0700, Junio C Hamano wrote: > The text in the MyFirstContribution documentation tells readers how > to send v1, how to send v2, and then how to respond to reviews, in > this order. It is unclear how much blame can be placed on this > text, but it somehow seems that senior community members need to > tell new contributors not to send updated interations of their s/interations/iterations/ > patches before having any review discussion on the current iteration > more often these days. > > Here is an attempt to improve the text by moving "how to send v2" > part much late in the text flow, after discussiong what should > happen in the review discussion. > > Strengthen the language about not sending the v2 out before engaging > in the discussion from "It is a good manners to do so" to "Do not > send v2 before you are done". Nit: I think this would have been easier to review if you first moved stuff around without changing the language yet and only then changing it in a second commit. Like this it's basically impossible to see what was moved and what needs reviewing. > diff --git c/Documentation/MyFirstContribution.adoc w/Documentation/MyFirstContribution.adoc > index 34bfa2e3a9..296ff97262 100644 > --- c/Documentation/MyFirstContribution.adoc > +++ w/Documentation/MyFirstContribution.adoc [snip] Now comes the rewritten part, everything above was simply moved. > +After a few days, you will hopefully receive a reply to your patchset > +with some comments. > + > + Nit: two newlines. > +Try to understand the reviewers' points, and ask questions if you do > +not understand what reviewers suggested. Reviewers may also ask you > +about what you wrote in the patchset, either in the proposed commit > +log message or in the changes themselves. You should answer these > +questions in your response messages, but often the reason why > +reviewers asked these questions to understand what you meant to write > +is because your patchset needed clarification to be understood. Make > +a mental note that when you send an improved version of the patch, > +make sure you explain your patch clearly enough so that the next > +person do not have to ask the same question again. s/do/does/ > +Try to find the best way to improve your patch they are commenting on > +together. Until you are done discussing the current round of reviews > +with your reviewers, do not start coding, let alone sending the next > +version of your patch. This may be a bit broad, as quite often I find myself exploring ideas before I can properly respond to review feedback. But maybe it's better to be this pushy given the recent trend of people not responding at all. > This way both you and your reviewers will save > +time. Reviewers can respond to your reasoning before you spend time > +preparing a version they may not agree with, and later do not need to > +inspect your v2 to figure out whether you implemented their comment or > +not. > > If you are going to push back on a comment, be polite and explain why you feel > your original is better; be prepared that the reviewer may still disagree with > @@ -1501,6 +1401,115 @@ changing history, but since it's local history which you haven't shared with > anyone, that is okay for now! (Later, it may not make sense to do this; take a > look at the section below this one for some context.) > > +After review discussion concludes for the current iteration, you will > +work on an improved version of your patch, and you will send the "v2". Makes sense. [snip] > +Same as with the first version, you can use `b4 send` to send out the second > +version. `b4` automatically bumps the version to `v2`, generates the range-diff > +against the previous iteration, and threads the new series as a reply to the > +cover letter of the first version. > + > + > + > + This is a lot of empty lines here :) Thanks! Patrick