Re: ChangeLogs?

[Hollis Blanchard]

On Oct 12, 2004, at 12:37 PM, Johan Rydberg wrote:
> Hollis Blanchard <address@hidden> 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.

A worthy goal... though you don't need a ChangeLog file for that when 
you have version control logs. Your "changeset comment" just goes in 
the commit message.

Also, you can see that changeset comments on a project like the Linux 
kernel are not nearly as verbose as the ChangeLog standards here.

So I guess I have two issues: 1) the file itself has been long 
obsolete, and 2) the contents of the file aren't as easy to read as 
truly high-level comments, and aren't as explicit as the patch they 
describe.

> 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.

Even CVS, which is not exactly a shining star of version control, can 
accomplish this task very easily through either "cvs log <file>" or 
"cvs annotate <file>".

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

The description "New function" may be easy to read when a diff is 
messy, but it won't help you discover the source of regressions.

> 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 eagerly await that day...

> > 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.

But "new variable" and "new function" isn't even close to telling you 
_what_ .

-Hollis