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

From: Junio C Hamano <gitster@pobox.com>
Date: Jan 23, 2022, 20:37 UTC
Message-ID: <xmqqilua89z5.fsf@gitster.g>

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