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