Re: [flame] NEWS file is useless

[Nicola Pero]

> > > ChangeLog has less information, in a less useful format, than the  
> > > svn logs and is a hold-over from CVS not storing repository-wide  
> > > change information sensibly.  With svn log, you can get a log of  
> > > change messages at any granularity that you like.
> >
> > I agree there is an overlap, but there are also some differences. ;-)
> >
> > Subversion records a single log message for an entire transaction,  
> > which might contain changes to a number of files.
> > A ChangeLog entry is supposed to contain a separate log message for  
> > every file that was changed.
>
> You realise that svn lets you commit changes to different files  
> separately, right?  If you have independent out-of-tree changes,  
> commit them separately (see r29053 to r29055; three commits, all  
> created together but committed separately to provide different log  
> messages).

I agree with your later point that you could simply write a ChangeLog  
entry in the subversion log - that way you still use subversion
transactions properly, but document the changes to all files. :-)

I don't think committing files separately makes sense instead -  
because you lose all the benefits of subversion transactions.  If you  
get interrupted
or lose network access between committing the separate files, the  
repository will be left in a broken state.  That is bad.

Also, I do like having in the logs the information that the changes  
are part of the same transaction.  You do a single diff and see all the
related changes to the different files, which is great. :-)

So I guess the solution to that would be instead to require ChangeLog  
entries to be committed to svn log.


> > Finally, the obvious advantage of a ChangeLog is that every source  
> > code distribution/tarball will include it.  Subversion logs are only
> > available if you use subversion.
>
> Subversion is available to anyone with access to the svn repository.

Yes, but in practice it is a pain for people who are not following the  
project.  When I install software from third-parties, I hate when they
don't include a properly detailed ChangeLog - eg, if I need to check  
if a certain bug in a certain file was fixed between version 1.7.4 and
1.7.5, I just want to download the 1.7.5 tarball and check the  
ChangeLog.  I don't want to have to set up whatever versioning system  
they
use just to check a single file - it takes time because every project  
uses a different one, etc.

I also occasionally work on gnustep-make offline, and the subversion  
logs are not available offline, while ChangeLogs are.


>  People can track it by subscribing to the RSS feed from cia.vc,  
> they can see an individual committer's changes by looking at the  
> timeline on Ohloh.net.

Sure, that is certainly good.


> If someone wants to do 'svn log >  ChangeLog' when creating the  
> tarballs, they can; just add it to the script you use to generate  
> the tarball.  Given that most tarball downloads are likely to be  
> from people who just want to build the code, however, it seems like  
> a waste of space.

It's definitely not a waste of space. ;-)

But if we were to agree that people would write ChangeLog entries in  
the subversion logs, then we could generate the ChangeLog from the  
subversion logs before release.
Even if in practice that can be hard, since all the interesting  
information for existing projects is currently in ChangeLogs, so we'd  
need to prepend to these ChangeLogs
the latest ChangeLog entries from the subversion logs, but the system  
would need to be able to figure out which logs to prepend and which to  
ignore.

Maybe a commit hook that copies the subversion log to the ChangeLog  
file makes more sense then, so the ChangeLog would automatically be  
updated whenever you commit.

If we want to go through this route, that would be ideal I guess.


> > So maybe we could adopt a different approach depending on the  
> > project.  I certainly think ChangeLogs are very good for the core
> > libraries.
>
> I still haven't seen a convincing argument for it.  Any of the  
> information that people write in the ChangeLog file they could also  
> write in the commit log.  It is impossible to make a commit without  
> writing a log message, it is easy to make a commit without editing  
> the ChangeLog (you could add a pre-commit hook that prevented this,  
> but no one has done so).

You're right that writing a subversion commit message is enforced,  
while writing a ChangeLog entry is not.

But on the other hand, ChangeLog entries must be in a certain format  
that require you to write a description of each change to each file,
while subversion log messages enforce no format and people tend to  
write extremely short, unexpressive messages such as "fixed bug"
or "improved performance" when they maybe have changed hundreds of  
lines in lots of different files.  When you're later trying to debug
some failures caused by an old change, you need some information on  
what they were trying to achieve, or why things were changed -
a more serious and detailed description of the changes.

So if we agree to move to subversion logs, we still need to somehow  
enforce people to write detailed ChangeLog entries (it's fine to have  
them
committed to the subversion logs) of what they did to each file.

Thanks