CannedResponses

   1 ----------------------------------------------------------------
   2 [the structure of a log message]
   3
   4 The usual way to compose a log message of this project is to
   5
   6  - Give an observation on how the current system work in the present
   7    tense (so no need to say "Currently X is Y", just "X is Y"), and
   8    discuss what you perceive as a problem in it.
   9
  10  - Propose a solution (optional---often, problem description
  11    trivially leads to an obvious solution in reader's minds).
  12
  13  - Give commands to the codebase to "become like so".
  14
  15 in this order.
  16
  17 To those who have been intimately following the discussion, it often
  18 is understandable without some of the above, but we are not writing
  19 for those who review the patches.  We are primarily writing for future
  20 readers of "git log" who are not aware of the review discussion we
  21 have on list, so we should give something to prepare them by setting
  22 the stage and stating the objective first, before going into how the
  23 patch solved it.
  24
  25 ------------------------------------------------------------------------
  26 [polish your history before sending]
  27
  28 We frown upon a patch series that makes mistakes in an earlier step,
  29 only to fix them in a later step.  The "git rebase -i" command helps
  30 us pretend to be more perfect developers than we actually are,
  31 whipping your patch series into a shape that builds one small step
  32 on top of another in a logical succession.  Such a patch series is
  33 easier to understand than a history that faithfully records all the
  34 stumbles the developer made until they reached the final solution.
  35
  36 ------------------------------------------------------------------------
  37 [not just respond, update the patches]
  38
  39 Not limited to this one, but when a reviewer says "this is not
  40 clear", it is often not a request to only clarify something, which
  41 is clear to any intelligent user of the end product, to a clueless
  42 reviewer, whose intelligence is below the target audience, in an
  43 e-mail response.  It is pointing out that the end product, either the
  44 patch text or the proposed log message, is not clear to target
  45 audience and needs update.
  46
  47 We would expect a review comment to be at least responded to either
  48 rebut or admit the issues raised.  It may be that a reviewer's point
  49 were missing the mark and the patches themselves were perfectly
  50 fine.
  51
  52 But all other cases, even when the reviewer's comment were missing
  53 the mark, such a confusion may have been the result of the patch
  54 text or the proposed log message being unclear.  Of course, the
  55 review comments may have been pointing out an actionable issue.
  56 They would hopefully lead to an improved version of the patches
  57 posted sometime later, so that we can conclude a topic and move
  58 ahead.
  59 ----------------------------------------------------------------
  60 [make us come to you, begging]
  61
  62 I've seen from time to time people ask "I am thinking of doing this;
  63 will a patch be accepted?  If so, I'll work on it." before showing
  64 any work, and my response always has been:
  65
  66  (1) We don't know how useful and interesting your contribution would
  67      be for our audience, until we see it; and
  68
  69  (2) If you truly believe in your work (find it useful, find writing
  70      it fun, etc.), that would be incentive enough for you to work
  71      on it, whether or not the result will land in my tree.  You
  72      should instead aim for something so brilliant that we would
  73      come to you begging for your permission to include it in our
  74      project.
  75
  76 ----------------------------------------------------------------
  77 [mailing list is the primary place]
  78
  79 One thing to note is that I do not respond to a pull request in private,
  80 and Github pull request, as I understand it, is very private in nature.
  81 The patches are to be reviewed on the main mailing list first.
  82
  83 It's OK to say "these patches are also available in my repository at
  84 Github whose URL is this" in the commentary part of the final submission
  85 message after the list reaches consensus that your change is a good thing,
  86 and that may reduce the chance of mistakes when I accept the patches
  87 especially if the series is large, so I am not saying that repositories
  88 people have Github have no value to my workflow.  But it will not come
  89 into the picture before the final submission phase.
  90
  91 ----------------------------------------------------------------
  92 [going incremental after hitting next]
  93
  94 Once a commit hits 'next', it gets improved only by piling incremental
  95 updates on top with explanation.  The idea is: if all of us thought it
  96 has seen enough eyeballs and is good enough for 'next', yet we later
  97 find there was something we all missed, that is worth a separate
  98 explanation, e.g., "The primary motivation behind the series is still
  99 good, but for such and such reasons we missed this case we are
 100 fixing."
 101
 102 Unless it turns out that the approach was fundamentally wrong and such
 103 an incremental update boils down to almost reverting the earlier one
 104 entirely and replacing it with the newer one.  In such a case, we do
 105 revert the earlier and replace it with the newer, in 'next'.
 106
 107 ----------------------------------------------------------------