standards: Style of Change Logs
1
1 6.8.2 Style of Change Logs
1 --------------------------
1
1 Here are some simple examples of change log entries, starting with the
1 header line that says who made the change and when it was installed,
1 followed by descriptions of specific changes. (These examples are drawn
1 from Emacs and GCC.)
1
1 1998-08-17 Richard Stallman <rms@gnu.org>
1
1 * register.el (insert-register): Return nil.
1 (jump-to-register): Likewise.
1
1 * sort.el (sort-subr): Return nil.
1
1 * tex-mode.el (tex-bibtex-file, tex-file, tex-region):
1 Restart the tex shell if process is gone or stopped.
1 (tex-shell-running): New function.
1
1 * expr.c (store_one_arg): Round size up for move_block_to_reg.
1 (expand_call): Round up when emitting USE insns.
1 * stmt.c (assign_parms): Round size up for move_block_from_reg.
1
1 It's important to name the changed function or variable in full.
1 Don't abbreviate function or variable names, and don't combine them.
1 Subsequent maintainers will often search for a function name to find all
1 the change log entries that pertain to it; if you abbreviate the name,
1 they won't find it when they search.
1
1 For example, some people are tempted to abbreviate groups of function
1 names by writing '* register.el ({insert,jump-to}-register)'; this is
1 not a good idea, since searching for 'jump-to-register' or
1 'insert-register' would not find that entry.
1
1 Separate unrelated change log entries with blank lines. Don't put
1 blank lines between individual changes of an entry. You can omit the
1 file name and the asterisk when successive individual changes are in the
1 same file.
1
1 Break long lists of function names by closing continued lines with
1 ')', rather than ',', and opening the continuation with '(' as in this
1 example:
1
1 * keyboard.c (menu_bar_items, tool_bar_items)
1 (Fexecute_extended_command): Deal with 'keymap' property.
1
1 When you install someone else's changes, put the contributor's name
1 in the change log entry rather than in the text of the entry. In other
1 words, write this:
1
1 2002-07-14 John Doe <jdoe@gnu.org>
1
1 * sewing.c: Make it sew.
1
1 rather than this:
1
1 2002-07-14 Usual Maintainer <usual@gnu.org>
1
1 * sewing.c: Make it sew. Patch by jdoe@gnu.org.
1
1 As for the date, that should be the date you applied the change.
1