@matheusbsbs / matheus-bagliano / commits / a6d8d11036

MyFirstContribition: answering questions is not the end of the story

A review exchange may begin with a reviewer asking "what did you mean by this phrase in your log message (or here in the doc)?", the author answering what was meant, and then the reviewer saying "ah, that is what you meant---then the flow of the logic makes sense". But that is not the happy end of the story. New contributors often forget that the material that has been reviewed in the above exchange is still unclear in the same way to the next person who reads it, until it gets updated. While we are in the vicinity, rephrase the verb "request" used to refer to comments by reviewers to "suggest"---this matches the contrast between "original" and "suggested" that appears later in the same paragraph, and more importantly makes it clearer that it is not like authors are to please reviewers' wishes but rather reviewers are merely helping authors to polish their commits. Reviewed-by: Emily Shaffer <emilyshaffer@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Junio C Hamano committed Nov 20, 2020 at 09:52 UTC a6d8d1103633f295ce6f738dcd5221389e8d5fd2
1 file changed +15 -1
Documentation/MyFirstContribution.txt
+15 -1
@@ -1142,11 +1142,25 @@ After a few days, you will hopefully receive a reply to your patchset with some
1142 comments. Woohoo! Now you can get back to work.
1143
1144 It's good manners to reply to each comment, notifying the reviewer that you have
1145 -made the change requested, feel the original is better, or that the comment
1145 +made the change suggested, feel the original is better, or that the comment
1146 inspired you to do something a new way which is superior to both the original
1147 and the suggested change. This way reviewers don't need to inspect your v2 to
1148 figure out whether you implemented their comment or not.
1149
1150 +Reviewers may ask you about what you wrote in the patchset, either in
1151 +the proposed commit log message or in the changes themselves. You
1152 +should answer these questions in your response messages, but often the
1153 +reason why reviewers asked these questions to understand what you meant
1154 +to write is because your patchset needed clarification to be understood.
1155 +
1156 +Do not be satisfied by just answering their questions in your response
1157 +and hear them say that they now understand what you wanted to say.
1158 +Update your patches to clarify the points reviewers had trouble with,
1159 +and prepare your v2; the words you used to explain your v1 to answer
1160 +reviewers' questions may be useful thing to use. Your goal is to make
1161 +your v2 clear enough so that it becomes unnecessary for you to give the
1162 +same explanation to the next person who reads it.
1163 +
1164 If you are going to push back on a comment, be polite and explain why you feel
1165 your original is better; be prepared that the reviewer may still disagree with
1166 you, and the rest of the community may weigh in on one side or the other. As