Re: [PATCH v4 0/2] MyFirstContribution: discuss then reroll

[Patrick Steinhardt <ps@pks.im>]

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