Re: [flame] NEWS file is useless

[David Chisnall]

On 26 Nov 2009, at 00:50, Nicola Pero wrote:

> > I'd be in favour of ditching NEWS and ChangeLog.
> >
> > 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).

> 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.   
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.  The information is available in a form that is easy for  
tools to process.

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.

> I still see your point - particularly for new software, written from  
> scratch by a single person and not yet really released, it is faster
> to just code it all and write short subversion logs for each commit  
> - it sounds superfluous to also write ChangeLog entries.  But
> once the software is quite finished and stable, is widely used and  
> released, and we're polishing it while being extremely careful
> not to break things, then a more careful approach where every change  
> is documented in great detail (and even redundantly) looks
> good to me. ;-)

Writing a ChangeLog entry does not make you more careful, it just  
makes you either write duplicate information, or split the useful  
information between the ChangeLog file and the svn log.

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

David

-- Send from my Jacquard Loom