ChangeLogs?

ChangeLogs?

[Hollis Blanchard]

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?

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.

There are also many ChangeLog features (such as say "macro" instead of 
"#define", and "variable" instead of "global") which are not described 
in the GCS, so I assume these are either project/maintainer-specific, 
or unwritten rules that all GNU members "just know". That makes it very 
difficult to follow them.

-Hollis

Re: ChangeLogs?

[Johan Rydberg]

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

Re: ChangeLogs?

[Hollis Blanchard]

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

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

Re: ChangeLogs?

[Johan Rydberg]

Hollis Blanchard <hollis@penguinppc.org> writes:

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

Commit messages are per-file, not per changeset.

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

Linux uses BitKeeper, a commerical changeset based VC system.

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

The thing is that you want a greater context than just a single
file.

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

I think it is.  That is exactly what you have changed: you have added
a new variable or function.  If you want to describe the variable or
function in greater detail, do so in the altered file (the source.)

~j

Re: ChangeLogs?

[Yoshinori K. Okuji]

I'd like to describe additional information on this topic.

The ChangeLog has two different purposes: information for tracking bugs 
and information on copyright. For the latter, it is very important to 
record who did what at when. "Why" does not matter here.

Suppose that you are a contributor to GNU Project and you are hired by a 
company (or maybe under the control of an university). If you forget to 
get a disclaimer from your company or the disclaimer is not signed by a 
proper person, your company might claim that GNU Project is not allowed 
to use your code. Then, we must detect which part of the code is owned 
by your company. If you provide only patches, it is too difficult to 
track all changes made by you.

For example, when we have a good ChangeLog, if you made a new function 
and another person rewrote the function from scratch afterwards, we can 
just grep the function name and get a conclusion that we don't have to 
drop the function in one minute. If we don't have any good ChangeLog... 
you should be able to imagine terrible work.

So, we must have a good ChangeLog always. It does not matter whether you 
use comments with a version control system or a plain-text file. 
Personally I believe that a plain-text file has more advatanges, but if 
you need to write logs anyway, is there any reason that you don't want 
to use the file ChangeLog?

I myself do this:

1. Write a change log.

2. Copy the log.

3. Commit my changes to the CVS with a comment pasted.

Okuji

Gnu Arch (was: Re: ChangeLogs?)

[Tomas Ebenlendr]

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

Hmm, and what about converting with Grub to GNU Arch? For me, it's main
advantage is branching. I will be able to hack for grub at any place,
because I'll comit my changes in my private archive. I'll merge into
mainstream only features, that will be accepted here.


-- 
                                 Tomas 'ebi' Ebenlendr
                                 http://get.to/ebik
                                 PF 2004.78270687867

Re: Gnu Arch (was: Re: ChangeLogs?)

[M. Gerards]

Quoting Tomas Ebenlendr <ebik@artax.karlin.mff.cuni.cz>:

> > 
> > 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.
> >
> 
> Hmm, and what about converting with Grub to GNU Arch? For me, it's main
> advantage is branching. I will be able to hack for grub at any place,
> because I'll comit my changes in my private archive. I'll merge into
> mainstream only features, that will be accepted here.

Savannah only supports CVS for now.  AFAIK that will be changed.

--
Marco