+++ b/README.md
@@ -3,7 +3,7 @@
Git - fast, scalable, distributed revision control system
=========================================================
-Git is a fast, scalable, distributed revision control system with an
+Git is a fast, scalable, and distributed revision control system with an
unusually rich command set that provides both high-level operations
and full access to internals.
--
2.21.0.392.gf8f6787159e-goog
----
[[now-what]]
== My Patch Got Emailed - Now What?
Please give reviewers enough time to process your initial patch before
sending an updated version. That is, resist the temptation to send a new
version immediately, because others may have already started reviewing
your initial version.
While waiting for review comments, you may find mistakes in your initial
patch, or perhaps realize a different and better way to achieve the goal
of the patch. In this case you may communicate your findings to other
reviewers as follows:
- If the mistakes you found are minor, send a reply to your patch as if
you were a reviewer and mention that you will fix them in an
updated version.
- On the other hand, if you think you want to change the course so
drastically that reviews on the initial patch would be a waste of
time (for everyone involved), retract the patch immediately with
a reply like "I am working on a much better approach, so please
ignore this patch and wait for the updated version."
Now, the above is a good practice if you sent your initial patch
prematurely without polish. But a better approach of course is to avoid
sending your patch prematurely in the first place.
Please be considerate of the time needed by reviewers to examine each
new version of your patch. Rather than seeing the initial version right
now (followed by several "oops, I like this version better than the
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.
[[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, notifying the reviewer that you have
made the change suggested, feel the original is better, or that the comment
inspired you to do something a new way which is superior to both the original
and the suggested change. This way reviewers don't 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.
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
you, and the rest of the community may weigh in on one side or the other. As
with all code reviews, it's important to keep an open mind to doing something a
different