[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [flame] NEWS file is useless
From: |
Richard Frith-Macdonald |
Subject: |
Re: [flame] NEWS file is useless |
Date: |
Thu, 26 Nov 2009 08:46:14 +0000 |
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.
- Re: XML GNUstep defaults (was: [flame] NEWS file is useless), (continued)
- Re: XML GNUstep defaults (was: [flame] NEWS file is useless), David Chisnall, 2009/11/27
- Re: XML GNUstep defaults (was: [flame] NEWS file is useless), Lars Sonchocky-Helldorf, 2009/11/27
- Re: XML GNUstep defaults (was: [flame] NEWS file is useless), Richard Frith-Macdonald, 2009/11/27
- Re: XML GNUstep defaults (was: [flame] NEWS file is useless), Lars Sonchocky-Helldorf, 2009/11/27
- Re: XML GNUstep defaults (was: [flame] NEWS file is useless), Richard Frith-Macdonald, 2009/11/27
Re: [flame] NEWS file is useless, David Chisnall, 2009/11/25
Re: [flame] NEWS file is useless,
Richard Frith-Macdonald <=
Re: [flame] NEWS file is useless, Nicola Pero, 2009/11/26
Re: [flame] NEWS file is useless, Richard Frith-Macdonald, 2009/11/26
Re: [flame] NEWS file is useless, Riccardo Mottola, 2009/11/26
Re: [flame] NEWS file is useless, Nicola Pero, 2009/11/26
Re: [flame] NEWS file is useless, Nicola Pero, 2009/11/26
Re: [flame] NEWS file is useless, Richard Frith-Macdonald, 2009/11/26
Re: [flame] NEWS file is useless, David Chisnall, 2009/11/26
Re: [flame] NEWS file is useless, Derek Fawcus, 2009/11/26
Re: [flame] NEWS file is useless, Riccardo Mottola, 2009/11/26
Re: [flame] NEWS file is useless, Riccardo Mottola, 2009/11/26