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.lattarini@gmail.com>

diff --git a/HACKING b/HACKING
index 84440a38c31977aeb81d0174130ba48678606d43..6b9895210813273bacc1eff540f814e7daf3086f 100644 (file)
--- 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")
+
+      <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 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.
+
+      <detailed list of touched files>
+
+* 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