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 <[EMAIL PROTECTED]> 
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.



Zope-Dev maillist  -  Zope-Dev@zope.org
**  No cross posts or HTML encoding!  **
(Related lists - http://mail.zope.org/mailman/listinfo/zope-announce
http://mail.zope.org/mailman/listinfo/zope )

Reply via email to