SubmittingPatches: clarify the expected commit log description
Earlier, 47afed5 (SubmittingPatches: itemize and reflect upon well written changes, 2009-04-28) added a discussion on the contents of the commit log message, but the last part of the new paragraph didn't make much sense. Reword it slightly to make it more readable. Update the "quicklist" to clarify what we mean by "motivation" and "contrast". Also mildly discourage external references. Signed-off-by: Junio C Hamano <gitster@pobox.com>
Junio C Hamano committed
Mar 8, 2011 at 16:58 UTC
d0f7dcbf424e1739437ffe477d87088ca6cb3432
1 file changed
+18
-8
Documentation/SubmittingPatches
+18
-8
@@ -10,10 +10,18 @@ Checklist (and a short version for the impatient):
10
description (50 characters is the soft limit, see DISCUSSION
11
in git-commit(1)), and should skip the full stop
12
- the body should provide a meaningful commit message, which:
13
- - uses the imperative, present tense: "change",
14
- not "changed" or "changes".
15
- - includes motivation for the change, and contrasts
16
- its implementation with previous behaviour
13
+ . explains the problem the change tries to solve, iow, what
14
+ is wrong with the current code without the change.
15
+ . justifies the way the change solves the problem, iow, why
16
+ the result with the change is better.
17
+ . alternate solutions considered but discarded, if any.
18
+ - describe changes in imperative mood, e.g. "make xyzzy do frotz"
19
+ instead of "[This patch] makes xyzzy do frotz" or "[I] changed
20
+ xyzzy to do frotz", as if you are giving orders to the codebase
21
+ to change its behaviour.
22
+ - try to make sure your explanation can be understood without
23
+ external resources. Instead of giving a URL to a mailing list
24
+ archive, summarize the relevant points of the discussion.
25
- add a "Signed-off-by: Your Name <you@example.com>" line to the
26
commit message (or just use the option "-s" when committing)
27
to confirm that you agree to the Developer's Certificate of Origin
@@ -90,7 +98,10 @@ your commit head. Instead, always make a commit with complete
98
commit message and generate a series of patches from your
99
repository. It is a good discipline.
100
93
-Describe the technical detail of the change(s).
101
+Give an explanation for the change(s) that is detailed enough so
102
+that people can judge if it is good thing to do, without reading
103
+the actual patch text to determine how well the code does what
104
+the explanation promises to do.
105
106
If your description starts to get too long, that's a sign that you
107
probably need to split up your commit to finer grained pieces.
@@ -99,9 +110,8 @@ help reviewers check the patch, and future maintainers understand
110
the code, are the most beautiful patches. Descriptions that summarise
111
the point in the subject well, and describe the motivation for the
112
change, the approach taken by the change, and if relevant how this
102
-differs substantially from the prior version, can be found on Usenet
103
-archives back into the late 80's. Consider it like good Netiquette,
104
-but for code.
113
+differs substantially from the prior version, are all good things
114
+to have.
115
116
Oh, another thing. I am picky about whitespaces. Make sure your
117
changes do not trigger errors with the sample pre-commit hook shipped