| Message ID | xmqqilua89z5.fsf@gitster.g (mailing list archive) |
|---|---|
| State | Accepted |
| Commit | fa1101afb66dfb3ad325ad135b7bed59e4067dd5 |
| Headers | show |
| Series | [RFC] Contributor doc: more on the proposed log message | expand |
On 2022-01-23 at 20:37:18, Junio C Hamano wrote: > 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? I think this is a good idea, since it differs from the way people usually discuss things outside of literature, and it's very common for this to trip people up.
On 24/01/22 3:02 am, brian m. carlson wrote: > On 2022-01-23 at 20:37:18, Junio C Hamano wrote: >> 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? > > I think this is a good idea, since it differs from the way people > usually discuss things outside of literature, and it's very common for > this to trip people up. > Precisely. I often get tripped up due to this whenever I write commit messages in general. So, good to have this clarified through a guideline.
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