[Zope-dev] Re: Extend specification of how to maintain the changelog

[Martijn Faassen]

Hi there,

Christian Theune wrote:
[snip]
> This results in the following properties for the CHANGES.txt:
> 
> - The trunk will contain sections for feature releases (e.g. 1.0, 1.1, ..) but
>   not bugfix releases (e.g. 1.0.2).
> 
> - Bug fixes will appear once in the feature release of the trunk (e.g. 1.1)
>   and once in each individual dot release of the various maintenance branches
>   that it went into (e.g. 1.0.y)
> 
> - There is not individual "large" CHANGES.txt that appears to be a simple
>   concatenation of the various changes on branches because we respect the
>   tree-ness of maintenance branches.

I'm +1 with this. This I think is easy enough to follow and doesn't 
require a lot of coordination between CHANGES.txt on release branches 
and trunk, which is good. It's also what I have been trying to do myself 
already. :)

One practice I've been wondering about is whether notes get appended to 
the bottom or the top of the section?

I.e. if I have this:

1.0 (unreleased)
----------------

Features
~~~~~~~~

* Foo

* Bar

Bug fixes
~~~~~~~~~

* Qux

* Hoi

And then I add a feature 'Kwack' or fix a bug 'Dag', where do I add 
them? To the top of the sections or to the bottom? I've noticed people 
do different things there, which sometimes leads to confusion (I might 
look at the bottom to see what new fixes there are, but I should be 
looking at the top for some more).

I myself am in favor of adding these things to the bottom of the 
individual sections, but I can see the argument for adding to the top of 
sections only.

(beyond all this, we should still have the ability to reorganize things 
if it makes sense before the release, it's just basically what happens 
between releases in normal activity that concerns me).

Regards,

Martijn