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

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

From
Junio C Hamano <gitster@pobox.com>
Date
Oct 22, 2026, 21:14 UTC
Message-ID
<20261022211404.380904-1-gitster@pobox.com>
In-Reply-To
<xmqqa4o94e0r.fsf@gitster.g>

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.

Hopefully this will be the final iteration of this series.
 1/2: MyFirstContribution: move "how to send v2" after discussing reviews
 2/2: MyFirstContribution: clarify that "reviewing" is a discussion
 Documentation/MyFirstContribution.adoc | 273 +++++++++++--------------
 1 file changed, 125 insertions(+), 148 deletions(-)
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.
     +
    -+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.
     +
    -+Do not iterate too quickly.  Limiting yourself to at most one
    -+iteration of the same patch series per day is good practice; it takes
    -+time to fully discuss the current version before working on the next.
    -+This allows multiple reviewers to comment, gives participants in
    -+different time zones a fair chance to participate, lets you batch
    -+feedback, and gives you time to digest comments before coding again.
    ++Do not iterate too quickly; at most one iteration per day is good
    ++practice.  This allows multiple reviewers to comment, gives
    ++participants in different time zones a fair chance, lets you batch
    ++feedback, and gives you time to digest comments before coding.
     +
    -+Knowing that you cannot immediately send another version encourages
    -+you to review your patches more carefully before sending.  You can
    -+catch small mistakes like typos and off-by-one errors yourself,
    -+allowing reviewers to focus on design, algorithms, and other
    -+substantive issues.
    ++Knowing you cannot immediately send another version encourages careful
    ++self-review, letting you catch small mistakes yourself so reviewers
    ++can focus on design and other substantive issues.
      
      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
-- 
2.56.0-336-g6ca398b529
Previous: Patrick SteinhardtNext: Junio C Hamano
Message 11 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.