summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAngelos Evripiotis <jevripiotis@bloomberg.net>2018-11-07 10:32:27 +0000
committerAngelos Evripiotis <angelos.evripiotis@gmail.com>2018-11-08 15:49:16 +0000
commitf764344057c1458a16db394d96d6b1d6132f4340 (patch)
treec458d8b26a9a2917baee120e872ded65564a0e17
parentf7231e90da32d020d8fc2e0488c1343aa0fefb61 (diff)
downloadbuildstream-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.rst10
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.