"Greg A. Woods" wrote:
>
> One of the problems with ChangeLog files is that unless they are
> *always* generated automatically they have a tendancy to be "different"
> in unpredictable ways from the "real" logs.
>
Right. They aren't authoritative. I don't see that they have to be.
They can describe, very quickly, what sort of thing was done and
when. If you need to find out exactly what was done, there's always
"cvs diff -u -D ... -D ... | less".
> Typically I always commit all the files at once with the same CVS
> command (something that's quite easy to do and now even more trivial to
> do with PCL-CVS) and thus I do end up with the identical log entry on
> each related revision in each file.
>
Right.
Still, if I were to wonder if there was a change done to support the
FOO environment variable, there's something to be said for reading
the ChangeLog as opposed to doing "cvs log" on likely-looking
files.
ISTM that there's several levels of documentation here, for different
uses. The ChangeLog is for humans to read, providing an overview of
changes done to the system. The "cvs log" is for humans to read,
providing a history of what was done to a given file and why. The
source code is for the machine (and, I certainly hope, humans) to
read, and that provides the definitive answer of what was done in
detail.
> But unfortunately even if you religiously use something like PCL-CVS to
> automatically update the ChangeLog file, or even "rcs2log" to generate
> it at release build time, it's still just a "copy" of what I would hope
> is the authoritative information.
>
Not necessarily even a direct copy of the authoritative information, but
still useful.
> There's a *LOT* more to be said of more formal documentation, including
> detailed release notes written by someone who reads both the log entries
> and the actual diffs! ;-)
>
That's another piece of documentation, which has the distinct advantage
of being useful for the paying customers. It can be done somewhat
post facto, and probably should at least be revised before shipping
to be more than a chronological list of random changes, some of which
the customers really don't need details of. ("The foo subsystem has
been changed to assure faster performance" is probably better than
"Changed event queue in foo to use a heap" and "Consolidated database
queries in foo initialization" and "Moved slow action from inner to
outer loop" for the customers.)
--
David H. Thornley Software Engineer
at CES International, Inc.: [EMAIL PROTECTED] or (763)-694-2556
at home: (612)-623-0552 or [EMAIL PROTECTED] or
http://www.visi.com/~thornley/david/
