From: Patrick Steinhardt Date: Fri, 23 Oct 2026 12:30:22 GMT Subject: Re: [PATCH v4 0/2] MyFirstContribution: discuss then reroll Message-ID: In-Reply-To: <20261022211404.380904-1-gitster@pobox.com> On Thu, Oct 22, 2026 at 02:14:02PM -0700, Junio C Hamano wrote: > The MyFirstContribution document tells readers how to send v1, how > to send v2, and then how to respond to reviews, in that order. It > uses a fairly weak language "it is a good manners to ..." to respond > to reviews before rerolling. > > On the mailing list, we find ourselves more and more frequently > having to tell new contributors not to send updated iterations of > their patches before having any review discussion on the current > iteration. > > Here is an attempt to rectify the situation. > > The first patch reorders the sections to explain how to send v1, how > to respond to reviews, before explaining how to send v2. > > The second patch rewrites the "how to respond to reviews" section to > strengthen the "it is a good manners" by replacing it with "do not > send v2 before you have finished discussing v1". > > Relative to v3, this rewrites the "responding to reviews" section > more tightly, shaving about 1/5 words, without losing substance. Is this me or is there no v3? I cannot find it online, either. > Range-diff against v3: > 1: e6f4a2a7ca = 1: 9db8ec4b98 MyFirstContribution: move "how to send v2" after discussing reviews > 2: 27f47d7d65 ! 2: 88abda272c MyFirstContribution: clarify that "reviewing" is a discussion > @@ Commit message > section largely duplicates the discussion on what to do after > getting a review, which is covered in the subsequent section. Also, > the "Reviewing" section does not make it clear from the beginning > - that reviewing is a process of discussion with your reviewers to design > - what the next iteration should look like. > + that reviewing is a process of discussion with your reviewers. > > Rewrite the "Reviewing" section with stronger language to discourage > sending a 'v2' iteration before working together with the reviewers > @@ Documentation/MyFirstContribution.adoc: previous one" patches over 2 days), revi > -reviewers' questions may be useful thing to use. Your goal is to make > -your v2 clear enough so that it becomes unnecessary for you to give the > -same explanation to the next person who reads it. > -+After a few days, you will hopefully receive a reply to your patch > -+series with some comments. Carefully read them to understand the > -+reviewers' perspective. Do not hesitate to ask for clarification if > -+you do not understand their suggestions. > ++After a few days, you may receive comments on your patch series. > ++Carefully read them to understand the reviewers' perspective, and do > ++not hesitate to ask for clarification. This overall includes way more changes than expected relative to v2, but I don't mind condensing our docs a bit. > -+Reviewers may also ask about what you wrote in the patch series, > -+either in the proposed commit log message or in the changes > -+themselves. Answer these questions in your response. Often, > -+reviewers ask because your patch series needs clarification to be > -+understood; use this as feedback to improve the clarity of your > -+writing. When answering, remember to update the patch itself so that > -+the next reader will not need to ask the same question. > ++Reviewers may also ask about your proposed commit log or the changes. > ++Answer these in your response. They often ask because the patch needs > ++clarification; use this feedback to improve your writing, and update > ++the patch so the next reader does not have to ask the same question. > + > -+Do not start coding, let alone send the next version of your patch, > -+until you have finished discussing the current one so both sides know > -+what to expect. This saves time for everyone. Reviewers can respond > -+to your explanation before you spend time preparing a patch they might > -+reject, and they will not have to inspect 'v2' only to find their > ++Do not start coding, much less send the next version, until you finish > ++discussing the current one and both sides know what to expect. This > ++saves time, lets reviewers respond before you write a patch they have > ++to reject, and avoids forcing them to inspect 'v2' only to find their > +concerns unaddressed. This is the new version that we've discussed. Patrick