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

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

From
Junio C Hamano <gitster@pobox.com>
Date
Oct 20, 2026, 23:22 UTC
Message-ID
<20261020232242.2217109-3-gitster@pobox.com>
In-Reply-To
<20261020232242.2217109-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 | 78 +++++++++++---------------
 1 file changed, 32 insertions(+), 46 deletions(-)
diff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc
index 682c797e3c..3fd6587e5a 100644
--- a/Documentation/MyFirstContribution.adoc
+++ b/Documentation/MyFirstContribution.adoc
@@ -1314,56 +1314,42 @@ 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 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.
+
+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.
+
+Do not start coding, much less send the next version of your patch,
+until you have finished discussing the current round of reviews with
+your reviewers.  This saves time for both you and your reviewers.
+They can respond to your reasoning before you spend time preparing a
+version they might reject, and they will not have to inspect your 'v2'
+to check if you addressed their concerns.
+
+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.
+
+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.
 
 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-321-g29a826976d
Previous: Patrick SteinhardtNext: Patrick Steinhardt
Message 7 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.