[668] in CVS-changelog-for-Kerberos-V5
ChangeLog usage
daemon@ATHENA.MIT.EDU (Mark Eichin)
Fri Jun 17 19:19:52 1994
From: Mark Eichin <eichin@cygnus.com>
Date: Fri, 17 Jun 1994 19:19:18 -0400
To: cvs-krb5@MIT.EDU
Here's what the GNU Coding Standards have to say about ChangeLogs; I'd
suggest we adobt them.
[extracted from] GNU Coding Standards
Copyright (C) 1992, 1993, 1994 Free Software Foundation
@set lastupdate 28 March 1994
@node Change Logs
@chapter 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 @kbd{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:
@example
* 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.
@end example
It's important to name the changed function or variable in full. Don't
abbreviate them; 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 @samp{* register.el
(@{insert,jump-to@}-register)}; this is not a good idea, since searching
for @code{jump-to-register} or @code{insert-register} would not find the
entry.
There's no need to describe the full purpose of the changes or how they
work together. It is better to put such explanations 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.
