CVS policy is that any change checked in be accompanied by a ChangeLog
entry (and a sanity.sh test, actually).
As far as advantages over $Log$ messages, you have only one file to look
at for log messages per directory, thus having a single entry for each
"job" checked in, even when the changes may have encompassed several
files. Each distribution also ends up with a copy of the ChangeLog, so
Joe or Jill Schmoe doesn't need access to the repository to glance through
the ChangeLog that came in their tar.gz'd archive. Thus, it becomes
"free" to maintain the "What's new" file for users to find out what
changed since the last version they downloaded. They can even use a
common tool like diff. Or a developer could use it to construct a more
concise "CHANGES" file. You can get some of this functionality from the
cvs2log.pl script and good log messages, but the information wouldn't
"automatically" be distributed without further work.
As for the fondness of the open source community in general for ChangeLog
files, I have a personal suspicion that, in addition to the above reasons,
the cynical among them might appreciate the ability to fork the code and
maintain much of the history information with a series of archived
distributions and without direct access to the source repository.
Of course it could be something simple like a legacy process that turned
out to still be somewhat useful. After all, even RCS hasn't been around
forever.
Anyway, I'd say that best policy is that any set of changes that seems to
be a good logical grouping and/or of possible interest to other developers
deserves a ChangeLog entry. A "good logical grouping" would be any
related set of changes, keeping the granularity at a level that the log
comment still makes some sense. Possible interest should encompass
approximately the same granularity level. If you changed 10 files to add
a new feature, the comment can mention the new feature and hopefully the
file list and comments in the files themselves will be help the next
developer that comes along to figure out why the feature doesn't work
right. :)
Derek
--
Derek Price CVS Solutions Architect
mailto:[EMAIL PROTECTED] OpenAvenue ( http://www.OpenAvenue.com )
--
The cost of living hasn't affected its popularity.
Laird Nelson wrote:
> Various posts here have been tangentially involved with ChangeLogs.
> Emacs has a ChangeLog mode. The free/open source communities seem to
> make great use of these things.
>
> What are they? Is there some URL or other source of information that
> someone can point me to on what a ChangeLog is, best practices on what
> it should look like, best practices on when it's edited, what it's used
> for, etc.?
>
> I feel like I'm missing something fairly important at a high level when
> I ask: what does a ChangeLog give you that $Log$ messages do not?
>
> We now return you to your regularly scheduled cvs discussion.
>
> Cheers,
> Laird
