6.8.2 Style of Change Logs

Here are some simple examples of change log entries, starting with the header line that says who made the change and when it was installed, followed by descriptions of specific changes. (These examples are drawn from Emacs and GCC.)

     1998-08-17  Richard Stallman  <rms@gnu.org>
     
     * register.el (insert-register): Return nil.
     (jump-to-register): Likewise.
     
     * sort.el (sort-subr): Return nil.
     
     * tex-mode.el (tex-bibtex-file, tex-file, tex-region):
     Restart the tex shell if process is gone or stopped.
     (tex-shell-running): New function.
     
     * expr.c (store_one_arg): Round size up for move_block_to_reg.
     (expand_call): Round up when emitting USE insns.
     * stmt.c (assign_parms): Round size up for move_block_from_reg.

It's important to name the changed function or variable in full. Don't abbreviate function or variable names, and don't combine them. Subsequent maintainers will often search for a function name to find all the change log entries that pertain to it; if you abbreviate the name, they won't find it when they search.

For example, some people are tempted to abbreviate groups of function names by writing ‘* register.el ({insert,jump-to}-register)’; this is not a good idea, since searching for jump-to-register or insert-register would not find that entry.

Separate unrelated change log entries with blank lines. When two entries represent parts of the same change, so that they work together, then don't put blank lines between them. Then you can omit the file name and the asterisk when successive entries are in the same file.

Break long lists of function names by closing continued lines with ‘)’, rather than ‘,’, and opening the continuation with ‘(’ as in this example:

     * keyboard.c (menu_bar_items, tool_bar_items)
     (Fexecute_extended_command): Deal with `keymap' property.

When you install someone else's changes, put the contributor's name in the change log entry rather than in the text of the entry. In other words, write this:

     2002-07-14  John Doe  <jdoe@gnu.org>
     
             * sewing.c: Make it sew.

rather than this:

     2002-07-14  Usual Maintainer  <usual@gnu.org>
     
             * sewing.c: Make it sew.  Patch by jdoe@gnu.org.

As for the date, that should be the date you applied the change.