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