git/list[1] front-page[2] threads[3] people[4] search[5] about
 

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

From
Patrick Steinhardt <ps@pks.im>
Date
Oct 23, 2026, 12:30 UTC
Message-ID
<attTXu2sSy93_wyq@pks.im>
In-Reply-To
<20261022211404.380904-1-gitster@pobox.com>
On Thu, Oct 22, 2026 at 02:14:02PM -0700, Junio C Hamano wrote:
Show 21 quoted lines
> 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.
Show 24 quoted lines
> 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.

Show 22 quoted lines
>     -+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
Previous: Junio C HamanoNext: Junio C Hamano
Message 14 of 15 in “MyFirstContribution: move preparation of v2 after review discussion”
  1. MyFirstContribution: move preparation of v2 after review discussionJunio C Hamano, Oct 19, 2026
  2. Patrick SteinhardtOct 20, 2026
  3. Junio C HamanoOct 20, 2026
  4. 0/2 MyFirstContribution: discuss then rerollJunio C Hamano, Oct 20, 2026
  5. 1/2 MyFirstContribution: move "how to send v2" after discussing reviewsJunio C Hamano, Oct 20, 2026
  6. Patrick SteinhardtOct 21, 2026
  7. 2/2 MyFirstContribution: clarify that "reviewing" is a discussionJunio C Hamano, Oct 20, 2026
  8. Patrick SteinhardtOct 21, 2026
  9. Junio C HamanoOct 21, 2026
  10. Patrick SteinhardtOct 22, 2026
  11. 0/2 MyFirstContribution: discuss then rerollJunio C Hamano, Oct 22, 2026
  12. 1/2 MyFirstContribution: move "how to send v2" after discussing reviewsJunio C Hamano, Oct 22, 2026
  13. 2/2 MyFirstContribution: clarify that "reviewing" is a discussionJunio C Hamano, Oct 22, 2026
  14. Patrick SteinhardtOct 23, 2026
  15. Junio C HamanoOct 23, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.