standards: Change Log Concepts

1 
1 6.8.1 Change Log Concepts
1 -------------------------
1 
1 You can think of the change log as a conceptual "undo list" which
1 explains how earlier versions were different from the current version.
1 People can see the current version; they don't need the change log to
1 tell them what is in it.  What they want from a change log is a clear
1 explanation of how the earlier version differed.  Each "entry" in a
1 change log describes either an individual change or the smallest batch
1 of changes that belong together, also known as a "change set".  For
1 later reference or for summarizing, sometimes it is useful to start the
1 entry with a one-line description (sometimes called a "title") to
1 describe its overall purpose.
1 
1    In the past, we recommended not mentioning changes in non-software
1 files (manuals, help files, media files, etc.) in change logs.  However,
1 we've been advised that it is a good idea to include them, for the sake
1 of copyright records.
1 
1    The change log file is normally called 'ChangeLog' and covers an
1 entire directory.  Each directory can have its own change log, or a
1 directory can use the change log of its parent directory--it's up to
1 you.
1 
1    Another alternative is to record change log information with a
1 version control system such as RCS or CVS. This can be converted
1 automatically to a 'ChangeLog' file using 'rcs2log'; in Emacs, the
1 command 'C-x v a' ('vc-update-change-log') does the job.
1 
1    For changes to code, there's no need to describe the full purpose of
1 the changes or how they work together.  If you think that a change calls
1 for explanation, you're probably right.  Please do explain it--but
1 please put the full explanation in comments in the code, where people
1 will see it whenever they see the code.  For example, "New function" is
1 enough for the change log when you add a function, because there should
1 be a comment before the function definition to explain what it does, how
1 to call it, and so on.
1 
1    For changes to files that do not support a comment syntax (e.g.,
1 media files), it is ok to include the full explanation in the change log
1 file, after the title and before the list of individual changes.
1 
1    The easiest way to add an entry to 'ChangeLog' is with the Emacs
1 command 'M-x add-change-log-entry'.  An individual change should have an
1 asterisk, the name of the changed file, and then in parentheses the name
1 of the changed functions, variables or whatever, followed by a colon.
1 Then describe the changes you made to that function or variable.
1