File: standards.info, Node: Change Logs, Next: Man Pages, Prev: NEWS File, Up: Documentation 6.8 Change Logs =============== Keep a change log to describe all the changes made to program source files. The purpose of this is so that people investigating bugs in the future will know about the changes that might have introduced the bug. Often a new bug can be found by looking at what was recently changed. More importantly, change logs can help you eliminate conceptual inconsistencies between different parts of a program, by giving you a history of how the conflicting concepts arose and who they came from. * Menu: * Change Log Concepts:: * Style of Change Logs:: * Simple Changes:: * Conditional Changes:: * Indicating the Part Changed::  File: standards.info, Node: Change Log Concepts, Next: Style of Change Logs, Up: Change Logs 6.8.1 Change Log Concepts ------------------------- You can think of the change log as a conceptual "undo list" which states how earlier versions were different from the current version. People can see the current version; they don't need the change log to tell them what is in it. What they want from a change log is a clear explanation of how the earlier version differed. Each "entry" in a change log describes either an individual change or the smallest batch of changes that belong together, also known as a "change set". It is a good idea to start the change log entry with a description of the overall change. This should be as long as needed to give a clear description. Then give a list of names of the entities or definitions that you changed, according to the files they are in, and what was changed in each one. *Note Style of Change Logs::. The change log file is normally called 'ChangeLog' and covers an entire directory. Each directory can have its own change log, or a directory can use the change log of its parent directory--it's up to you. Instead of using a file named 'ChangeLog', you can record the change log information as log entries in a version control system such as RCS or CVS. This can be converted automatically to a 'ChangeLog' file using 'rcs2log'; in Emacs, the command 'C-x v a' ('vc-update-change-log') does the job. The best place to explain how parts of the new code work with other code is in comments in the code, not in the change log. If you think that a change calls for explanation of _why_ the change was needed--that is, what problem the old code had such that it required this change--you're probably right. Please put the explanation in comments in the code, where people will see it whenever they see the code. An example of such an explanation is, "This function used to be iterative, but that failed when MUMBLE was a tree." (Though such a simple reason would not need this kind of explanation.) The best place for other kinds of explanation of the change is in the change log entry. The easiest way to add an entry to 'ChangeLog' is with the Emacs command 'M-x add-change-log-entry'. An individual change should have an asterisk, the name of the changed file, and then in parentheses the name of the changed functions, variables or whatever, followed by a colon. Then describe the changes you made to that function or variable.  File: standards.info, Node: Style of Change Logs, Next: Simple Changes, Prev: Change Log Concepts, Up: Change Logs 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 * 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. Don't put blank lines between individual changes of an entry. You can omit the file name and the asterisk when successive individual changes 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 * sewing.c: Make it sew. rather than this: 2002-07-14 Usual Maintainer * sewing.c: Make it sew. Patch by address@hidden. As for the date, that should be the date you applied the change.