From: Junio C Hamano Date: Tue, 20 Oct 2026 23:22:42 GMT Subject: [PATCH v2 2/2] MyFirstContribution: clarify that "reviewing" is a discussion 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 --- 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