From f764344057c1458a16db394d96d6b1d6132f4340 Mon Sep 17 00:00:00 2001 From: Angelos Evripiotis Date: Wed, 7 Nov 2018 10:32:27 +0000 Subject: 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. --- CONTRIBUTING.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'CONTRIBUTING.rst') 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. -- cgit v1.2.1