Re: ChangeLogs?

[Johan Rydberg <jrydberg@night.trouble.net>]

Hollis Blanchard <hollis@penguinppc.org> writes:

> ChangeLog files are new to me, so could somebody help explain them?
> (Yes I've read the GNU Coding Standards.)
>
> It seems to me that the ChangeLog is an anachronism born in a time
> before source control systems, and a poor substitute for the actual
> patch. The GCS does not explain the role of the ChangeLog file in the
> context of a system like CVS, and I find that to be a glaring
> omission. Why would you want a ChangeLog when CVS can tell you what
> *really* happened?

ChangeLogs is must like you said, an inheritance from the time when VC
systems wasn't wide spread.  But it still fills an function.  CVS, and
before that, RCS, are both file-based VC systems.  By adding an
ChangeLog entry describing all changes you get the _feeling_ of a
changeset / patchset based VC system.  This is also the reason why you
describe _what_ changed, and not _why_ it changed.

Another reason for having ChangeLogs is that it is easier to read an
ChangeLog than browsing through large amounts of patches.  Say that
person A commits a patch, or patchset.  Then persons B, C and D
commits other changes.  And then it's time for you to commit your
patch, but suddenly nothing works.  You get a segmentation error in
the function "foobar".  What to do?  Well, the simplest thing is to
bring up the ChangeLog, search for "foobar", and see if any of these
changes could possibly be the reason for your troubles.

A third reason is that it at times can be hard to interpret patches,
even if they are in unidiff format.

Summary: It is easy to read ChangeLogs.

But ChangeLogs will most likely go away, or at least change, when
changeset based VC system (GNU Arch, for example) gets more wide
spread usage.

> I guess my real problem is the level of detail in the ChangeLog: way
> too much, or way too little. If you want that much detail, read the
> patch. "New variable" doesn't give you enough detail anyways: What
> type is it? Where is it initialized? Where is it used? Or it gives you
> too much detail: maybe you just want to know that there's a firmware
> bug in certain systems that we work around by setting a flag so later
> code knows to avoid it.

Remember that you should only describe _what_ you have changed.  If
you want to clearify something, put it in a comment in the source.

Just my thoughts.

~j