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

[PATCH v4 2/2] MyFirstContribution: clarify that "reviewing" is a discussion

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

The latter half of the "We sent our initial patch. Now what?" 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.

Rewrite the "Reviewing" section with stronger language to discourage sending a 'v2' iteration before working together with the reviewers to prepare for it. In particular, replace the weak "it is a good manners to do so" with a firmer "do not send v2 before you are done."

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/MyFirstContribution.adoc | 69 +++++++++-----------------
 1 file changed, 23 insertions(+), 46 deletions(-)
diff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc
index 682c797e3c..c58253fd54 100644
--- a/Documentation/MyFirstContribution.adoc
+++ b/Documentation/MyFirstContribution.adoc
@@ -1314,56 +1314,33 @@ previous one" patches over 2 days), reviewers would strongly prefer if a
 single polished version came 2 days later instead, and that version with
 fewer mistakes were the only one they would need to review.
 
-This consideration applies not only when going from the initial patch to v2,
-but also to later iterations of the same series. There is no fixed rule for how
-long to wait before sending a new version. A useful default is to send at most
-one new version of the same patch series per day. This gives multiple reviewers
-time to comment, gives reviewers across time zones a fair chance to
-participate, lets you batch feedback together, and gives you time to think
-through the comments you received. Knowing that you should not immediately send
-another version also encourages you to review the patches more carefully before
-sending them, catch small mistakes such as typos and off-by-one errors
-yourself, and let reviewers spend more of their attention on design,
-algorithms, and other substantial issues.
-
-The right timing depends on the topic and the feedback. Larger series usually
-need more review time. If the only comments so far are minor, such as typo
-fixes, it often makes sense to wait a little longer in case deeper reviews are
-still coming. If the comments call for substantial rework, do not rush out an
-updated version before you have reviewed the larger changes carefully. Instead,
-reply to the review that prompted the rewrite, say that you are preparing a
-substantial rework, and mention which parts of the current series will become
-obsolete so reviewers can avoid spending time on them until the updated series
-is ready.
-
 
 [[reviewing]]
 === Responding to Reviews
 
-After a few days, you will hopefully receive a reply to your patchset with some
-comments. Woohoo! Now you can get back to work.
-
-It's good manners to reply to each comment in the mailing list discussion
-instead of letting the next version of your patch be your only response. Tell
-the reviewer whether you plan to make the suggested change, keep the original,
-or pursue a different approach. This way 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.
-
-Reviewers may 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.
-
-Do not be satisfied by just answering their questions in your response
-and hear them say that they now understand what you wanted to say.
-Update your patches to clarify the points reviewers had trouble with,
-and prepare your v2; the words you used to explain your v1 to answer
-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 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 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, 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; 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 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: Junio C HamanoNext: Patrick Steinhardt
Message 13 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.