Re: [Groff] new automake system

[Werner LEMBERG]

> So If I understand correctly the format:
>   - First you put a title or sum up and general explanations.

First, you should have a single line (not longer than 78 chars) that
describes the issue – this is mainly for programs like `gitk', which
shows a summary of commits in its main window.

Then it's a good idea to have an empty line, followed by a detailed
description of the commit, if necessary or useful.

>   - All entries starting with '* should first refer to a file.

Yes.  A file name, followed by a function name in parentheses,
probably followed by a related #ifdef-Name in brackets (if
applicable).  For longer functions with e.g. a large switch statement,
it makes sense to add the name of the `case' field in angle brackets:



  * src/bar/foo.c (bla-bla-func) <'a'> [HAVE_BAZ]: Description...

Note that all such lines are indented by a tab.  The lines starting in
column 1 have the format

  date  name  e-mail

Note that there are *two* spaces between date and name (and name and
e-mail).  The e-mail address should be surrounded by angle brackets.

> But should the git commit systematically contain all these entries
> (it seems it's not always the case)?

For code changes, there should be an entry.  I first create a
ChangeLog entry, then simply copy it to the commit message, removing
the tabs, and omitting date, name, and e-mail.

White-space changes and minor documentation changes don't need a
ChangeLog entry.

More details can be found in `standards.info':

  http://www.gnu.org/prep/standards/standards.html#Change-Logs


    Werner