[RFC] Policy change for ChangeLog

[Chris Lyttle]

On Fri, 2005-12-02 at 15:45 +0100, Christian Stimming wrote:
> Derek Atkins schrieb:
> >> On Thu, 2005-12-01 at 16:25 -0500, Chris Shoemaker wrote:
> >>
> >>> Comments?
> >>
> >> This change is fine with me, and sounds good.
> > 
> > Before we go ahead with this, I'd like to hear from Chris Lyttle
> > and Christian Stimming..  They're the ones who usually use the
> > ChangeLog to generate the NEWS and release notes.  I'd like to
> > hear if they are willing to accept the new process going forward.
> 
> I wouldn't throw away our ChangeLog convention too quickly. It used to 
> be (and still is) a good compromise between readability and verbosity.
> 
> The problem is that we don't have any experience with maintaining that 
> obnoxious "big picture file", which supposedly would be the NEWS file. 
> So far that file has been used for the release notes until 1.7.8 but is 
> unused since them. We do have experience with the Changelog file, and 
> these are good experiences so far. Developer tend to copy the ChangeLog 
> entry to the CVS/SVN commit log or vice versa, so this convention 
> doesn't seem to put too much of an additional work on the developers.

Um, actually even tho HEAD currently doesn't have the NEWS file from
1.8.x it is there and NEWS has been updated for every release so far. I
know, I do those updates 'manually' from looking at the log messages in
the Changelog and watering it down for public consumption. The 1.8.x
NEWS file should probably be merged back over to HEAD.
> 
> As for compiling the release notes: Definitely the "svn log" is way too 
> verbose for the normal release note compilation. Currently working 
> through anything between 100 or 500 lines of ChangeLog during 1.8.x was 
> doable, but thousands of lines of "svn log" really is way too much.
> 
> IMHO our ChangeLog convention or what developers did from that meant 
> that all the totally-trivial things were already filtered out, and this 
> would be lost if we don't use ChangeLog at all. The point is that 
> ChangeLog still is the "note collection for the developers", whereas the 
> NEWS is the "note collection for the public", i.e. only that stuff that 
> as the time of writing is already considered fundamentally important. 
> Many things that might not be considered important at the time of 
> writing will not be added to the NEWS file, whereas they are added to 
> the ChangeLog -- where the release note collectors will pick it up at 
> the time when it's required.
> 
> > At some level it's OUR job as developers to make OTHERS lives
> > easier..  While we should certainly use tools to make OUR lives
> > easier, we need to think of who is using what we create and how
> > they use it.  Making life easier for us at their expense is NOT
> > okay.  So, I'd like to hear from wilddev and cstim first.
> 
> I prefer if there still is a place where every developer adds a note for 
> the majority of the non-trivial commits. Doesn't have to be the 
> ChangeLog, but IMHO that's the easiest way to do this. The NEWS file 
> IMHO is "too official"/"too public" for that goal.
> 

I agree with the idea of only doing a ChangeLog for each major release.
It is necessary to be able to look back over how the current release is
developed IMHO. I really would not like to see a ChangeLog file
auto-generated from commit messages. I've seen far to many of those go
by with 'updated blah for foobar' which really doesn't give me enough to
write the NEWS file with. The ChangeLog nearly always has that sort of
info. Anyway, since I started doing this I thought the point of the
ChangeLog was to relay why the dev's were changing things to the public
who might be interested in that info. I know I quite often look into a
tarball's ChangeLog to figure out what files have changed in a new
release of something or to see if a bug I filed was actually fixed. So I
guess my point here is ChangeLog isn't only for dev's even tho they
mainly update it.

Chris
-- 
RedHat Certified Engineer #807302549405490.
Checkpoint Certified Security Expert 2000 & NG
--------------------------------------------
        |^|
        | |   |^|
        | |^| | |  Life out here is raw 
        | | |^| |  But we will never stop
        | |_|_| |  We will never quit 
        | / __> |  cause we are Metallica
        |/ /    |
        \       /
         |     |
--------------------------------------------