Subject: [RFC] Contributor doc: more on the proposed log message

From: Junio C Hamano <[email-masked]>
Date: Sun, 23 Jan 2022 12:37:18 -0800

I have been thinking about making it more clear why we care about
the log message, and noticed that we have CodingGuidelines and
SubmittingPatches, both are specifically targetted for the
contributors of THIS project (not to users contributing to a project
that happens to use Git).

I think the first thing to fix is that we have the "describe your
changes well" section in the latter, as if it is not part of the
code that is covered by CodingGuidelines.  You formulate the thought
on how to explain/sell your changes to others, and you sift the text
you add to help fellow developers into the ones you leave in in-code
comments and in the proposed log message, while you code.  I am
tempted to propose moving the part about proposed log message from
SubmittingPatches to CodingGuidelines for this reason.

Independent of the above, here is a small update I would add to
clarify the project convention on the log message.

Thoughts?

---
 Documentation/SubmittingPatches | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git c/Documentation/SubmittingPatches w/Documentation/SubmittingPatches
index 92b80d94d4..11d0c85988 100644
--- c/Documentation/SubmittingPatches
+++ w/Documentation/SubmittingPatches
@@ -142,6 +142,13 @@ The body should provide a meaningful commit message, which:
 
 . alternate solutions considered but discarded, if any.
 
+[[present-tense]]
+The problem statement that describes the status quo is written in the
+present tense.  Write "The code does X when it is given input Y",
+instead of "The code used to do Y when given input X".  You do not
+have to say "Currently"---the status quo in the problem statement is
+about the code _without_ your change, by project convention.
+
 [[imperative-mood]]
 Describe your changes in imperative mood, e.g. "make xyzzy do frotz"
 instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy