diff options
author | Junio C Hamano <gitster@pobox.com> | 2024-02-23 00:00:01 -0800 |
---|---|---|
committer | Junio C Hamano <gitster@pobox.com> | 2024-02-23 00:00:01 -0800 |
commit | 0a75d7853cd718fc08aaad1fdfbef380535c6892 (patch) | |
tree | 0407de5b8f4d44b065c0e416c930fa9ac4754145 | |
parent | d9de65ab5e36c6fecba49add82cca268ca50edc7 (diff) | |
download | git-0a75d7853cd718fc08aaad1fdfbef380535c6892.tar.gz |
Meta/CannedResponses
A collection of suggestions and guidance messages we often give to
relatively new contributors.
-rw-r--r-- | CannedResponses | 95 |
1 files changed, 95 insertions, 0 deletions
diff --git a/CannedResponses b/CannedResponses new file mode 100644 index 0000000000..74044e483b --- /dev/null +++ b/CannedResponses @@ -0,0 +1,95 @@ +---------------------------------------------------------------- +[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 work in the present + tense (so no need to say "Currently X is Y", just "X is Y"), 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 the codebase to "become like so". + +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. + +------------------------------------------------------------------------ +[polish your history] + +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. + +---------------------------------------------------------------- +[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'. + +---------------------------------------------------------------- |