Go to the first, previous, next, last section, table of contents.

Change Logs

Keep a change log for each directory, describing the changes made to source files in that directory. 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 eliminate conceptual inconsistencies between different parts of a program; they can give you a history of how the conflicting concepts arose.

Use the Emacs command M-x add-change to start a new entry in the change log. An entry 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.

Separate unrelated 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.

Here are some examples:

* 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.

There's no need to describe here the full purpose of the changes or how they work together. It is better to put this explanation in comments in the code. That's why just "New function" is enough; there is a comment with the function in the source to explain what it does.

However, sometimes it is useful to write one line to describe the overall purpose of a large batch of changes.

You can think of the change log as a conceptual "undo list" which explains 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.

When you change the calling sequence of a function in a simple fashion, and you change all the callers of the function, there is no need to make individual entries for all the callers. Just write in the entry for the function being called, "All callers changed."

When you change just comments or doc strings, it is enough to write an entry for the file, without mentioning the functions. Write just, "Doc fix." There's no need to keep a change log for documentation files. This is because documentation is not susceptible to bugs that are hard to fix. Documentation does not consist of parts that must interact in a precisely engineered fashion; to correct an error, you need not know the history of the erroneous passage.


Go to the first, previous, next, last section, table of contents.