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

[yuppie]

Hi!


Second try. My first response to this lead to a discussion about 
immediate or delayed syncing of CHANGES.txt. That was not my point.

Christian Theune wrote:
> On Wed, Jun 18, 2008 at 11:20:17AM -0400, Fred Drake wrote:
>> On Wed, Jun 18, 2008 at 10:21 AM, Christophe Combelles <ccomb at free.fr> wrote:
>>> The risk is that people will think the bug is fixed in 3.6.0 and not in the
>>> 3.5 branch.
>> That's a general documentation risk, and I don't think anyone else has
>> come up with a better way to deal with this.  If you can find an
>> example that solves this without excess burden on the maintainers,
>> that would be really good to hear about.
> 
> The problem here is in managing the release notes in a single file within
> version control is easy to do.
> 
> Everything else that makes this more clear either requires tedious manual
> tasks or really hard automation.
> 
> Additionally, if you're bound to a branch, I guess it would be really easy to
> see what's changed there -- the release notes of that branch will tell you.
> 
> The issue is that providing a 'correct' flat view of a tree structure is
> really hard in this case. The version numbering does not imply a time line!

There is always *one* well defined current maintenance branch. Version 
numbering *does* imply a time line if you ignore old maintenance 
branches. It's not hard at all to get this right.

> Even when merging all the release notes, one would see the same change appear
> in 3.5.3, 3.6.4 and 3.7.0 eventually. Now, as you would read it from top to
> bottom, you might also think that it wasn't fixed in 3.5, even if you look
> there.

You don't have to make things more complicated than they are right now. 
Nobody wants to merge release notes from old maintenance branches to 
newer branches. Changes on those branches are just backports.

> (Agreed, the lookup would be much simpler.)

I think it is important to make it simple to look up what's new.

> I guess that merging release notes automatically would actually be easier in
> the format that I proposed ...

I doubt that. In the format you propose the change note has to be placed 
in a different context. If we group changes on the trunk the same way as 
on the current maintenance branch, the context will always be the same.


Cheers,

	Yuppie