[RFC] Policy change for ChangeLog

Chris Shoemaker c.shoemaker at cox.net
Fri Dec 2 11:52:11 EST 2005


On Fri, Dec 02, 2005 at 03:45:35PM +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. 

I think this is a shame.  We should have *somewhere* to collect
incremental "big picture" and "public-view" notes.  How about this: We
open an undated entry at the top of NEWS, to which we can
incrementally add content.  At release time, we bang the content into
release-log shape, possibly supplementing material from ChangeLog,
date it, version it, "close" it, and open a new empty, undated one for
the next release.

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

I agree that making release notes directly from the commit messages is
very difficult.  I think we should try to do it "as we go", and polish
it at release time.

BTW, you seem to expect that the ChangeLog is/would be significantly
smaller than "svn log", but I don't think it is, neither in practice
(just compare) nor in policy (from README.svn: "There must be a
ChangeLog entry for every commit. If you discover that you only
committed half the files you meant to and need to fix that up you do
not need a new ChangeLog entry.  But in general, ChangeLog entries are
mandatory. Changes with out ChangeLog entries will be reverted.")  So,
the same difficulty exists in both cases, but I think it can be
resolved by a better use of NEWS.

> 
> 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 think developers should add a note for *every* commit (even trivial
ones).  We currently do this in the commit message.  We should also
somehow ensure that these messages are distributed with the source,
even when svn isn't used, and it makes sense that this be as a
ChangeLog.  Separately, we can accumulate "pre-release notes" at the
top of NEWS to ease burden of writing release notes.

What do you think?

-chris


More information about the gnucash-devel mailing list