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. See 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 (what problem the old code had), 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 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.