diff options
| author | Angelos Evripiotis <jevripiotis@bloomberg.net> | 2018-11-07 10:32:27 +0000 |
|---|---|---|
| committer | Angelos Evripiotis <angelos.evripiotis@gmail.com> | 2018-11-08 15:49:16 +0000 |
| commit | f764344057c1458a16db394d96d6b1d6132f4340 (patch) | |
| tree | c458d8b26a9a2917baee120e872ded65564a0e17 | |
| parent | f7231e90da32d020d8fc2e0488c1343aa0fefb61 (diff) | |
| download | buildstream-f764344057c1458a16db394d96d6b1d6132f4340.tar.gz | |
contributing: emphasise the 'why' in commits
Explain why it's useful to mention the decisions made for a change and
provide links for background, e.g. issue numbers.
My general experience of git histories is that folks don't do enough
explaining, so it's great we have a contributing section for it.
I've found it's easier for folks to stick to rules when they know the
practical reasons for them, so provide some.
| -rw-r--r-- | CONTRIBUTING.rst | 10 |
1 files changed, 10 insertions, 0 deletions
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 72a0bd116..dcd21e07d 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -156,6 +156,16 @@ number must be referenced in the commit message. Fixes #123 +Note that the 'why' of a change is as important as the 'what'. + +When reviewing this, folks can suggest better alternatives when they know the +'why'. Perhaps there are other ways to avoid an error when things are not +frobnicated. + +When folks modify this code, there may be uncertainty around whether the foos +should always be frobnicated. The comments, the commit message, and issue #123 +should shed some light on that. + In the case that you have a commit which necessarily modifies multiple components, then the summary line should still mention generally what changed (if possible), followed by a colon and a brief summary. |