GNU Info

(standards.info)Change Log Concepts

---

Next: Style of Change Logs Up: Change Logs

---

Enter node , (file) or (file)node

Change Log Concepts
-------------------

   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.

   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.

   Another alternative is to record change log information with 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.

   There's no need to describe the full purpose of the changes or how
they work together.  If you think that a change calls for explanation,
you're probably right.  Please do explain it--but please put the
explanation in comments in the code, where people will see it whenever
they see the code.  For example, "New function" is enough for the
change log when you add a function, because there should be a comment
before the function definition to explain what it does.

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

   The easiest way to add an entry to `ChangeLog' is with the Emacs
command `M-x add-change-log-entry'.  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.