[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Tue, 12 Oct 2004 14:07:49 -0500
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
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
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
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