Removed uncommon acronyms in the "Checklist" section. I had to look up "iow" online, but this documentation should stand alone (without online access) as well as commit messages. Leave wiggle room for including URLs in commit messages. Having both summaries of mailing list discussions as well as URLs in commit messages gives the reader the choice of how deep into history they wish to dig. Modify the section about trivial changes slightly... it makes more sense that it is discouraging diffs pasted in emails as opposed to patches generated with "git am". Remove recommendations on commit messages from the "Make separate commits for logically separate changes" section, they are covered well and explicitly in the "Checklist" section on top. This section need not repeat same, and the deleted text doesn't really apply to the section it was under. Also remove irrelevant text about good commit messages. The only relevant part of that paragraph was the first sentence about breaking apart big commits into separate patches. Consistently use the phrase "commit message" to mean the chunk of text that describes a commit. Also in "Checklist", make the third bullet under "...a meaningful commit message, which:" flow better grammatically by adding "mentions". Relevant mailing list discussion: http://thread.gmane.org/gmane.comp.version-control.git/168481/focus=168717 Signed-off-by: Adam Monsen <haircut@xxxxxxxxx> --- I realize that this commit probably violates the very virtues it recommends by having a long commit message and fixing several things in one shot. Let me know if you'd like me to break it apart. Also, I may of course have made further errors. It does adhere to the subject of cleaning up commit message tips. Hope this helps, -Adam Documentation/SubmittingPatches | 38 ++++++++++++++++---------------------- 1 files changed, 16 insertions(+), 22 deletions(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index c3b0816..3f8bff5 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -10,18 +10,19 @@ Checklist (and a short version for the impatient): description (50 characters is the soft limit, see DISCUSSION in git-commit(1)), and should skip the full stop - the body should provide a meaningful commit message, which: - . explains the problem the change tries to solve, iow, what - is wrong with the current code without the change. - . justifies the way the change solves the problem, iow, why - the result with the change is better. - . alternate solutions considered but discarded, if any. + . explains the problem the change tries to solve, in other words, + what is wrong with the current code without the change. + . justifies the way the change solves the problem, in other words, + why the result with the change is better. + . mentions alternate solutions considered but discarded, if any. - describe changes in imperative mood, e.g. "make xyzzy do frotz" instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy to do frotz", as if you are giving orders to the codebase to change its behaviour. - try to make sure your explanation can be understood without - external resources. Instead of giving a URL to a mailing list - archive, summarize the relevant points of the discussion. + external resources. Instead of providing only a URL to a + mailing list archive, summarize the relevant points of the + discussion. - add a "Signed-off-by: Your Name <you@xxxxxxxxxxx>" line to the commit message (or just use the option "-s" when committing) to confirm that you agree to the Developer's Certificate of Origin @@ -52,14 +53,14 @@ Checklist (and a short version for the impatient): Long version: -I started reading over the SubmittingPatches document for Linux +I started reading over the SubmittingPatches document for the Linux kernel, primarily because I wanted to have a document similar to -it for the core GIT to make sure people understand what they are -doing when they write "Signed-off-by" line. +it for core GIT to make sure people understand what they are +doing when they include a "Signed-off-by" line. But the patch submission requirements are a lot more relaxed -here on the technical/contents front, because the core GIT is -thousand times smaller ;-). So here is only the relevant bits. +here on the technical/contents front, because the core GIT is a +thousand times smaller ;-). So here are just the relevant bits. (0) Decide what to base your work on. @@ -93,7 +94,7 @@ commit is the tip of the topic branch. (1) Make separate commits for logically separate changes. Unless your patch is really trivial, you should not be sending -out a patch that was generated between your working tree and +out a diff that was generated between your working tree and your commit head. Instead, always make a commit with complete commit message and generate a series of patches from your repository. It is a good discipline. @@ -103,15 +104,8 @@ that people can judge if it is good thing to do, without reading the actual patch text to determine how well the code does what the explanation promises to do. -If your description starts to get too long, that's a sign that you -probably need to split up your commit to finer grained pieces. -That being said, patches which plainly describe the things that -help reviewers check the patch, and future maintainers understand -the code, are the most beautiful patches. Descriptions that summarise -the point in the subject well, and describe the motivation for the -change, the approach taken by the change, and if relevant how this -differs substantially from the prior version, are all good things -to have. +If your commit message starts to get too long, that's a sign that you +probably need to split your commit into finer grained pieces. Oh, another thing. I am picky about whitespaces. Make sure your changes do not trigger errors with the sample pre-commit hook shipped -- 1.7.2.3 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html