On 02/25/2012 08:38 PM, Stefano Lattarini wrote: > > But I should definitely improve HACKING and have it document the > standards and best practice for commit logs (since the GCS are sadly > weak and out-of-date in this regard). > And here is my attempt. WDYT? I will push in a couple of days if there is no objection.
Regards, Stefano
>From 2abf7351e62f7f33e6f8d7e2ee065b28269f0581 Mon Sep 17 00:00:00 2001 Message-Id: <2abf7351e62f7f33e6f8d7e2ee065b28269f0581.1330203810.git.stefano.lattar...@gmail.com> From: Stefano Lattarini <stefano.lattar...@gmail.com> Date: Sat, 25 Feb 2012 22:01:17 +0100 Subject: [PATCH] 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 <stefano.lattar...@gmail.com> --- HACKING | 65 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 files changed, 63 insertions(+), 2 deletions(-) diff --git a/HACKING b/HACKING index 84440a3..5229928 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 @@ -165,6 +163,69 @@ 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") + + <reference to relevant bugs, if any> + + 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 of 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. + + <detailed list of touched files> + + Signed-off-by: A. U. Thor <a.u.t...@example.org> + +* The <detailed list of touched files> 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 * Use "make check" and "make maintainer-check" liberally. -- 1.7.9
