CannedResponses

----------------------------------------------------------------
[the structure of a log message]

The usual way to compose a log message of this project is to

 - Give an observation on how the current system works in the
   present tense (so no need to say "Currently X is Y", or
   "Previously X was Y" to describe the state before your change;
   just "X is Y" is enough), and discuss what you perceive as a
   problem in it.

 - Propose a solution (optional---often, problem description
   trivially leads to an obvious solution in reader's minds).

 - Give commands to somebody editing the codebase to "make it so",
   instead of saying "This commit does X".

in this order.

To those who have been intimately following the discussion, it often
is understandable without some of the above, but we are not writing
for those who review the patches.  We are primarily writing for future
readers of "git log" who are not aware of the review discussion we
have on list, so we should give something to prepare them by setting
the stage and stating the objective first, before going into how the
patch solved it.


------------------------------------------------------------------------
[trim your quote]

Please do not force your readers scroll through huge quoted material
to find your comments, when your comments do not address anything
there.  Trim your quote and leave enough context to understand the
discussion.  See Documentation/ReviewingGuidelines.adoc, which says

- If a patch is long, you are encouraged to delete parts of it that are
  unrelated to your review from the email reply. Make sure to leave enough
  context for readers to understand your comments!

------------------------------------------------------------------------
[polish your history before sending]

We frown upon a patch series that makes mistakes in an earlier step,
only to fix them in a later step.  The "git rebase -i" command helps
us pretend to be more perfect developers than we actually are,
whipping your patch series into a shape that builds one small step
on top of another in a logical succession.  Such a patch series is
easier to understand than a history that faithfully records all the
stumbles the developer made until they reached the final solution.

------------------------------------------------------------------------
[not just respond, update the patches]

Not limited to this one, but when a reviewer says "this is not
clear", it is often not a request to only clarify something, which
is clear to any intelligent user of the end product, to a clueless
reviewer, whose intelligence is below the target audience, in an
e-mail response.  It is pointing out that the end product, either the
patch text or the proposed log message, is not clear to target
audience and needs update.

We would expect a review comment to be at least responded to either
rebut or admit the issues raised.  It may be that a reviewer's point
were missing the mark and the patches themselves were perfectly
fine.

But all other cases, even when the reviewer's comment were missing
the mark, such a confusion may have been the result of the patch
text or the proposed log message being unclear.  Of course, the
review comments may have been pointing out an actionable issue.
They would hopefully lead to an improved version of the patches
posted sometime later, so that we can conclude a topic and move
ahead.

----------------------------------------------------------------
[not just reroll, but respond to reviews]

After getting review comments but before sending a new iteration of
your patches, do respond to the review e-mails directly to develop a
dialog between you as the author and your reviewers.

A new iteration of a patch is harder to read without such a dialog
telling reviewers what the author thought after getting suggestions in
earlier reviews.

Did they agree and took the suggestion?  Did they disagree but took
the suggestion anyway, and if so why did they think the suggested
changes are not good?  Did they disagree and did not take the
suggestion and if so why?  They changed the code but not in the way
suggested in the review, but why the new way was thought to be better
than both the original and the reviewer input?

These are natural questions reviewers want to get answered, and some
of them can be answered by reading a new iteration of patch (e.g., did
they or did they not update the patch?) but not others (e.g., why did
they or did they not do so?).

Don't make reviewers feel as if they are talking to silent machine
that takes an earlier iteration of the patch and their reviews as
input and spits out a new iteration as output.

----------------------------------------------------------------
[understand reviews, respond, work, and then reroll]

A response to reviews on the N-th round must come long before
sending the v(N+1) round of patches.  Some contributors send them
after v(N+1), or immediately before, but the proper time to respond
is soon after receiving the reviews on vN and having had enough time
to understand the comments, before starting work on v(N+1).  Only
after that work is complete would you send the new patches.  Hence,
we expect the time between vN and v(N+1) from real contributors to
be measured in days, not hours.  Whenever I see vN responses arrive
after or immediately before the v(N+1) patches, or worse, no
response at all but just the new patches, it smells fishy.

----------------------------------------------------------------
[make us come to you, begging]

I've seen from time to time people ask "I am thinking of doing this;
will a patch be accepted?  If so, I'll work on it." before showing
any work, and my response always has been:

 (1) We don't know how useful and interesting your contribution would
     be for our audience, until we see it; and

 (2) If you truly believe in your work (find it useful, find writing
     it fun, etc.), that would be incentive enough for you to work
     on it, whether or not the result will land in my tree.  You
     should instead aim for something so brilliant that we would
     come to you begging for your permission to include it in our
     project.

----------------------------------------------------------------
[mailing list is the primary place]

One thing to note is that I do not respond to a pull request in private,
and Github pull request, as I understand it, is very private in nature.
The patches are to be reviewed on the main mailing list first.

It's OK to say "these patches are also available in my repository at
Github whose URL is this" in the commentary part of the final submission
message after the list reaches consensus that your change is a good thing,
and that may reduce the chance of mistakes when I accept the patches
especially if the series is large, so I am not saying that repositories
people have Github have no value to my workflow.  But it will not come
into the picture before the final submission phase.

----------------------------------------------------------------
[going incremental after hitting next]

Once a commit hits 'next', it gets improved only by piling incremental
updates on top with explanation.  The idea is: if all of us thought it
has seen enough eyeballs and is good enough for 'next', yet we later
find there was something we all missed, that is worth a separate
explanation, e.g., "The primary motivation behind the series is still
good, but for such and such reasons we missed this case we are
fixing."

Unless it turns out that the approach was fundamentally wrong and such
an incremental update boils down to almost reverting the earlier one
entirely and replacing it with the newer one.  In such a case, we do
revert the earlier and replace it with the newer, in 'next'.

----------------------------------------------------------------
[do not iterate too quickly]

After sending your patches out, it would be nice to give potential
reviewers at least 24 hours to ensure people anywhere on the globe
have a chance to comment, and a chance for you to respond to them,
before sending your next iteration.

When responding to a review comment that causes you to drastically
change the course of the series, it is nice to give potential
reviewers at least 24 hours to ensure they have a chance to voice
their opinions, before sending an updated series based on that
comment, because suggested changes in such a comment may be
controversial and deserve discussion.  After seeing you spend some
time already to adjust to one opinion on such a discussion, others may
feel discouraged to make you redo your series again even whey they
think the suggested changes are not taking us in the right direction.