Re: [flame] NEWS file is useless

[Richard Frith-Macdonald]

On 26 Nov 2009, at 01:10, David Chisnall wrote:

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

Agreed ... it's sometimes a bit inconvenient to use svn that way (and leaves a 
small window in which people can check out inconsistent code), but not a real 
problem.

>> 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 agree with Nicola here ... it's very, very far from being a waste of space 
... people do need to be able to see the changes made to the code.
So your suggestion of having a script make a ChangeLog automatically from the 
svn logs makes a *lot* of sense.

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

Unfortunately true ... I must confess that, since the ChangeLog is the official 
repository of this information, I tend to write more informative stuff there 
than in the svn logs ... so there's duplication, but it's lossy/imperfect 
because it's just easier that way, especially when working in environments 
without cut-and-paste (yes, I still do that quite a bit) and when I suddenly 
get interrupted.

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

I really don't like the current situation where we have a split between 
historical/official practices of using ChangeLog and newcomers using svn log 
entries.  I think my own behavior has been 'corrupted' by the widespread use of 
svn logs ... I suspect the quality of my ChangeLog entries has dropped, not for 
any good reason but just because of a slight mental conflict at the point when 
I'm committing changes.

While ChangeLog has its advantages, the fact that we are using svn, which has 
it's own logs means that the svn logs really have to 'win' if you want to avoid 
the duplication.

I would like to support dropping ChangeLog.  For this to work we need two 
things:

1. technical changes to address any disadvantages of svn logs.
2. official policy change

For (1) I think the only real issue is that of generating a ChangeLog file from 
the svn logs for inclusion in any distributions.  I think Nicola might lead on 
that, as we create releases and snapshots using special targets in 
gnustep-make, and those targets would need to be updated to generate the 
ChangeLog files.  Perhaps adding an explicit 'ChangeLog' target would be good 
too. 

For (2) I think we need Greg to take a lead as maintainer of the project, 
finding out what everyones opinions are, and making a judgment and announcement 
etc.  It would be good to consider exactly how much (if any) information we 
want to present in NEWS/ReleaseNotes ... my preference would be for minimal 
information there, and a pointer to a generated ChangeLog for details.  This 
would require a policy that svn log entries should be suitable for app 
developers (users of the libraries), not just for people writing the libraries 
themselves.

Lastly ... I'm not even sure that the historical policies on ChangeLog etc are 
written down anywhere or if it's all just something I was told years ago.  It's 
quite likely that what we have been doing was GNU policy and there are 
documents describing it on some FSF website.  It's also quite possible that 
such official GNU policy has changed over the years and we might be quite 
outdated by now.   If there is any current official GNU policy, we ought to 
consider it  in case someone wiser than us has already provided good rules that 
we might adopt.