SubmittingPatches: itemize and reflect upon well written changes
The SubmittingPatches file was trimmed down from a somewhat overwhelming set of requirements from the Linux Kernel equivalent; however perhaps a little of it can be returned without making the text too long. Signed-off-by: Sam Vilain <sam@vilain.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Sam Vilain committed
Apr 28, 2009 at 02:38 UTC
47afed5dc17faf10fde18789b17cf6ebff829cf4
1 file changed
+13
-1
Documentation/SubmittingPatches
+13
-1
@@ -6,9 +6,13 @@ Checklist (and a short version for the impatient):
6
- check for unnecessary whitespace with "git diff --check"
7
before committing
8
- do not check in commented out code or unneeded files
9
- - provide a meaningful commit message
9
- the first line of the commit message should be a short
10
description and should skip the full stop
11
+ - the body should provide a meaningful commit message, which:
12
+ - uses the imperative, present tense: "change",
13
+ not "changed" or "changes".
14
+ - includes motivation for the change, and contrasts
15
+ its implementation with previous behaviour
16
- if you want your work included in git.git, add a
17
"Signed-off-by: Your Name <you@example.com>" line to the
18
commit message (or just use the option "-s" when
@@ -62,6 +66,14 @@ Describe the technical detail of the change(s).
66
67
If your description starts to get too long, that's a sign that you
68
probably need to split up your commit to finer grained pieces.
69
+That being said, patches which plainly describe the things that
70
+help reviewers check the patch, and future maintainers understand
71
+the code, are the most beautiful patches. Descriptions that summarise
72
+the point in the subject well, and describe the motivation for the
73
+change, the approach taken by the change, and if relevant how this
74
+differs substantially from the prior version, can be found on Usenet
75
+archives back into the late 80's. Consider it like good Netiquette,
76
+but for code.
77
78
Oh, another thing. I am picky about whitespaces. Make sure your
79
changes do not trigger errors with the sample pre-commit hook shipped