From 3b5f6115437f568a530c9162ede552ad728f0690 Mon Sep 17 00:00:00 2001 From: Stefano Lattarini Date: Sat, 25 Feb 2012 22:01:17 +0100 Subject: hacking: document format for git commit messages * HACKING (Writing a good commit message): New section. (Working with git): A related minor adjustment. Signed-off-by: Stefano Lattarini --- HACKING | 63 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 61 insertions(+), 2 deletions(-) (limited to 'HACKING') diff --git a/HACKING b/HACKING index 84440a38c..6b9895210 100644 --- a/HACKING +++ b/HACKING @@ -146,8 +146,6 @@ the active branches descending from the buggy commit. This offers a simple way to fix the bug consistently and effectively. -* When referring to older commits, use 'git describe' output as pointer. - * There may be a number of longer-lived feature branches for new developments. They should be based off of a common ancestor of all active branches to which the feature should or might be merged later. The next branch may @@ -164,6 +162,67 @@ release. For next, and for feature branches, the announcement for the branch should document rewinding policy. +================================================================ += Writing a good commit message + +* Here is the general format that Automake's commit messages are expected + to follow. See the further points below for clarifications and minor + corrections. + + topic: brief description (this is the "summary line") + + + + Here goes a more detailed explanation of why the commit is needed, + and a general overview of what it does, and how. This section is + optional, but you are expected to provide it more often than not. + + And if the detailed explanation is quite long or detailed, you can + want to break it in more paragraphs. + + Then you can add references to relevant mailing list discussions + (if any), with proper links. But don't take this as an excuse for + writing incomplete commit messages! The "distilled" conclusions + reached in such discussions should have been placed in the + paragraphs above. + + Finally, here you can thank people that motivated or helped the + change. So, thanks to John Doe for bringing up the issue, and to + J. Random Hacker for providing suggestions and testing the patch. + + + +* The is mandatory but for the most + trivial changes, and should follows the GNU guidelines for ChangeLog + entries (described explicitly in the GNU Coding Standards); it might + be something of this sort: + + * some/file (func1): Improved frobnication. + (func2): Adjusted accordingly. + * another/file (foo, bar): Likewise. + * tests/foo.tap: New test. + * tests/Makefile.am (TESTS): Add it. + +* If your commit fixes an automake bug registered in the tracker (say + numbered 1234), you should put the following line after the summary + line: + + This change fixes automake bug#1234. + +* If your commit is just related to the given bug report, but does not + fix it, you might want to add a line like this instead: + + This change is related to automake bug#1234. + +* When referring to older commits, use 'git describe' output as pointer. + But also try to identify the given commit by date and/or summary line + if possible. Examples: + + Since yesterday's commit, v1.11-2019-g4d2bf42, ... + + ... removed in commit 'v1.11-1674-g02e9072' of 01-01-2012, + "dist: ditch support for lzma"... + ================================================================ = Test suite -- cgit v1.2.1