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

[yuppie]

Hi!


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!
> 
> 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. (Agreed, the lookup would be much simpler.)

Why do we maintain a CHANGES.txt file? Who reads it and why?

The audience I have in mind are users of released versions. They read 
CHANGES.txt to figure out what's new in a release.

Let's take Zope 2 as an example:

Most people will currently use version 2.10.6. If they read CHANGES.txt 
of Zope 2.11.0, they want to know what's new in 2.11.0 compared to 
2.10.6. CHANGES.txt of Zope 2.11.0 is 233 lines long and provides 
(almost) exactly what they need.

You propose to mix in all the change notes made between 2.10.0 and 
2.10.6 with a total of another 240 lines. That makes it almost 
impossible to figure out what's new compared to 2.10.6.

On the 2.10 branch we have the information which bugfix belongs to which 
2.10 release. You just have to copy that information from the branch to 
the trunk. No big burden for the maintainers, but a big win for the users.


Cheers,

	Yuppie