[PATCH v2 3/3] SubmittingPatches: explain why we care about log messages

From

Junio C Hamano <gitster@pobox.com>

Date

Jan 26, 2022, 23:42 UTC

Message-ID

<20220126234205.2923388-4-gitster@pobox.com>

In-Reply-To

<20220126234205.2923388-1-gitster@pobox.com>

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/SubmittingPatches | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 7225a0fb52..9c5977fac3 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -110,6 +110,34 @@ run `git diff --check` on your changes before you commit.
 [[describe-changes]]
 === Describe your changes well.
 
+The log message that explains your changes is as much important as the
+changes themselves.  Your code may be clearly written with in-code
+comment to sufficiently explain how it works with the surrounding
+code, but those who need to fix or enhance your code in the future
+will need to know _why_ your code does what it does, for a few reasons:
+
+. Your code may be doing something differently from what you wanted it
+  to do.  Writing down what you actually wanted to achieve will help
+  them fix your code and make it do what it should have been doing
+  (also, you often discover your own bug while writing your log
+  message yourself).
+
+. Your code may be doing things that were only necessary for your
+  immediate needs (e.g. "do X to directories" without implementing or
+  even designing what is to be done on files).  Writing down why you
+  excluded what the code does not do will help guide future developers
+  (e.g. writing down "we do X to directories, because directories have
+  characteristic Y" would help them infer "oh, files also have the
+  same characteristic Y, so perhaps doing X to them would also make
+  sense?".  Or "we don't do the same X to files, because ..." will
+  help them decide if the reasoning is sound (in which case they do
+  not waste time extending your code to cover files), or reason
+  differently (in which case they explain why they extend your code to
+  cover files, too).
+
+The goal of your log message is to convey the _why_ behind your
+change to help them.
+
 The first line of the commit message should be a short description (50
 characters is the soft limit, see DISCUSSION in linkgit:git-commit[1]),
 and should skip the full stop.  It is also conventional in most cases to

-- 
2.35.0-155-g0eb5153edc