diff options
author | Angelos Evripiotis <jevripiotis@bloomberg.net> | 2018-11-07 10:32:27 +0000 |
---|---|---|
committer | Angelos Evripiotis <jevripiotis@bloomberg.net> | 2018-11-07 13:06:43 +0000 |
commit | 8d8446963429cd37b36801feb1d7f10355c4fc3f (patch) | |
tree | 5b82199ab6816c8f8f73c107698ebe1b12713e09 | |
parent | 5e838749b9b4173751922d5a5c43f2561637db67 (diff) | |
download | buildstream-aevri/contributing_gitlab.tar.gz |
contributing: emphasise the 'why' in commitsaevri/contributing_gitlab
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. |