Extend specification of how to maintain the changelog
Hi, This post refers to Philipp's guide for `Maintaining software in the Zope software repository` [1]. I noticed that I kept getting confused about maintaining CHANGES.txt entries when merging bug fixes around, looked around a bit and thought I'd share my findings. First, I think we have a terminology issue as the standard form of 'ChangeLog' refers to individual changes, pretty much as what is recorded by subversion's log. (See [2] and [3].) What I understand from the Wikipedia entries for Changelog [4] and Release notes [5] is that what we record in the CHANGES.txt files is closer to release notes than a changelog. This is just an observation -- I'm happy with the actual content of what we use to put into the CHANGES.txt file. The core problem in maintenance is that I wasn't sure how to record bug fixes that are applied over multiple branches (trunk and maybe one or two maintenance branches). I discussed this a bit and found the following way that looks reasonable: - The CHANGES.txt is mainainted for each release series in their branch (obviously). - The first section marks the next released (as specified in [1]). - A change on a branch is recorded in the next unreleased section. (Merges of the same fix over multiple branches are not recorded in different places on the other branches.) 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 find that Philipp's guide could be extended/clarified a bit more about this. Comments, suggestions, etc. welcome. Christian [1] http://svn.zope.org/*checkout*/Sandbox/philikon/foundation/maintaining-softw... [2] http://www.gnu.org/prep/standards/html_node/Change-Logs.html#Change-Logs [3] http://www.gnu.org/software/guile/changelogs/guile-changelogs_toc.html [4] http://en.wikipedia.org/wiki/Changelog [5] http://en.wikipedia.org/wiki/Release_notes -- Christian Theune · ct@gocept.com gocept gmbh & co. kg · forsterstraße 29 · 06112 halle (saale) · germany http://gocept.com · tel +49 345 1229889 7 · fax +49 345 1229889 1 Zope and Plone consulting and development
Some clarifications: On Wed, Jun 18, 2008 at 12:09:27PM +0200, Christian Theune wrote:
- The first section marks the next released (as specified in [1]).
Easier to read: The first section is the 'next release' section which refers to a currently unreleased version.
- A change on a branch is recorded in the next unreleased section. (Merges of
And this is easier to read as: A change (on a branch) is recorded in the 'next release' section -- Christian Theune · ct@gocept.com gocept gmbh & co. kg · forsterstraße 29 · 06112 halle (saale) · germany http://gocept.com · tel +49 345 1229889 7 · fax +49 345 1229889 1 Zope and Plone consulting and development
On Jun 18, 2008, at 12:09 , Christian Theune wrote:
- A change on a branch is recorded in the next unreleased section. (Merges of the same fix over multiple branches are not recorded in different places on the other branches.)
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)
Just for clarification, does this imaginary scenario describe what you mean? - I am fixing a problem in the 1.2-branch of my Foobar product and note the fix in CHANGES.txt on the 1.2-branch - I merge the fix to all other currently supported release branches, but do not note the fix in CHANGES.txt those branches - I merge the fix to the trunk and *do* note it in its CHANGES.txt So the fix would result in two CHANGES.txt files being updated: On the branch where I fixed the problem initially, and on the trunk. On the imaginary 1.2-branch, the entry would be in the section for the next upcoming sub-release. On the trunk CHANGES.txt, which then only carries subsections for each feature (major) release the fix will be noted under the next (yet unreleased) feature release version number. If this is the case I do like the fact that the trunk will always show all fixes. jens
Hi, On Wed, Jun 18, 2008 at 01:11:46PM +0200, Jens Vagelpohl wrote:
Just for clarification, does this imaginary scenario describe what you mean?
- I am fixing a problem in the 1.2-branch of my Foobar product and note the fix in CHANGES.txt on the 1.2-branch
- I merge the fix to all other currently supported release branches, but do not note the fix in CHANGES.txt those branches
Yes you do. The 1.1 branch would note in its 1.1.x release that the fix was applied.
- I merge the fix to the trunk and *do* note it in its CHANGES.txt
Yes.
So the fix would result in two CHANGES.txt files being updated: On the branch where I fixed the problem initially, and on the trunk. On the imaginary 1.2-branch, the entry would be in the section for the next upcoming sub-release. On the trunk CHANGES.txt, which then only carries subsections for each feature (major) release the fix will be noted under the next (yet unreleased) feature release version number.
If this is the case I do like the fact that the trunk will always show all fixes.
Mechanically every branch's CHANGES.txt shows all changes from the perspective of the particular branch. When branching off the trunk, you stop recording changes from that branch on the trunk, so the changelogs of the individual branches will always look like: TRUNK: Includes changes for the releases 1.0, 1.1, 1.2, and the upcoming feature release 1.3 Branch 1.2: Includes changes for the release 1.0, 1.1, 1.2, 1.2.1, 1.2.x, ... Branch 1.1: Includes changes leading to 1.0, 1.1, 1.1.1, 1.1.x, ..., Christian -- Christian Theune · ct@gocept.com gocept gmbh & co. kg · forsterstraße 29 · 06112 halle (saale) · germany http://gocept.com · tel +49 345 1229889 7 · fax +49 345 1229889 1 Zope and Plone consulting and development
On Jun 18, 2008, at 14:32 , Christian Theune wrote:
Hi,
On Wed, Jun 18, 2008 at 01:11:46PM +0200, Jens Vagelpohl wrote:
Just for clarification, does this imaginary scenario describe what you mean?
- I am fixing a problem in the 1.2-branch of my Foobar product and note the fix in CHANGES.txt on the 1.2-branch
- I merge the fix to all other currently supported release branches, but do not note the fix in CHANGES.txt those branches
Yes you do. The 1.1 branch would note in its 1.1.x release that the fix was applied.
- I merge the fix to the trunk and *do* note it in its CHANGES.txt
Yes.
So in essence it sounds like changes will be noted in CHANGES.txt for *all* those branches and the trunk that they're applied to, and the only difference is the version numbers showing in each CHANGES.txt file, with the trunk only ever showing feature release numbers? jens
On Wed, Jun 18, 2008 at 02:48:22PM +0200, Jens Vagelpohl wrote:
So in essence it sounds like changes will be noted in CHANGES.txt for *all* those branches and the trunk that they're applied to, and the only difference is the version numbers showing in each CHANGES.txt file, with the trunk only ever showing feature release numbers?
Yes. -- Christian Theune · ct@gocept.com gocept gmbh & co. kg · forsterstraße 29 · 06112 halle (saale) · germany http://gocept.com · tel +49 345 1229889 7 · fax +49 345 1229889 1 Zope and Plone consulting and development
On Jun 18, 2008, at 15:07 , Christian Theune wrote:
On Wed, Jun 18, 2008 at 02:48:22PM +0200, Jens Vagelpohl wrote:
So in essence it sounds like changes will be noted in CHANGES.txt for *all* those branches and the trunk that they're applied to, and the only difference is the version numbers showing in each CHANGES.txt file, with the trunk only ever showing feature release numbers?
Yes.
OK, got it. For what it's worth, I'm in favor of this approach. For the CMF we currently have a policy which I have always found hard to explain, where changes are _not_ noted on every branch that receives them, and the trunk CHANGES.txt is always in a strange state. At least I've always been confused, but I have tried to follow that policy since it was agreed on a long time ago. jens
Christian Theune a écrit :
Hi,
This post refers to Philipp's guide for `Maintaining software in the Zope software repository` [1].
I noticed that I kept getting confused about maintaining CHANGES.txt entries when merging bug fixes around, looked around a bit and thought I'd share my findings.
(...)
I find that Philipp's guide could be extended/clarified a bit more about this.
Comments, suggestions, etc. welcome.
Hi Christian, let's take a real package as an example (on which I recently did some merges) CHANGES.txt on the trunk: http://svn.zope.org/zope.app.container/trunk/CHANGES.txt?rev=87370 CHANGES.txt on the 3.5 branch: http://svn.zope.org/zope.app.container/branches/3.5/CHANGES.txt?rev=87428 Given what you said, what should these files look like? Christophe
Christian
[1] http://svn.zope.org/*checkout*/Sandbox/philikon/foundation/maintaining-softw... [2] http://www.gnu.org/prep/standards/html_node/Change-Logs.html#Change-Logs [3] http://www.gnu.org/software/guile/changelogs/guile-changelogs_toc.html [4] http://en.wikipedia.org/wiki/Changelog [5] http://en.wikipedia.org/wiki/Release_notes
Hi, On Wed, Jun 18, 2008 at 01:23:20PM +0200, Christophe Combelles wrote:
Hi Christian,
let's take a real package as an example (on which I recently did some merges)
CHANGES.txt on the trunk: http://svn.zope.org/zope.app.container/trunk/CHANGES.txt?rev=87370
CHANGES.txt on the 3.5 branch: http://svn.zope.org/zope.app.container/branches/3.5/CHANGES.txt?rev=87428
Given what you said, what should these files look like?
*Almost* as they look like now, except that the changes from 3.5.1+ on the trunk would be visible as a change to 3.6. It would have only one entry for 3.5 which would be 3.5.0; and probably the pre-releases leading to the stable 3.5.0. Christian -- Christian Theune · ct@gocept.com gocept gmbh & co. kg · forsterstraße 29 · 06112 halle (saale) · germany http://gocept.com · tel +49 345 1229889 7 · fax +49 345 1229889 1 Zope and Plone consulting and development
Christian Theune a écrit :
Hi,
On Wed, Jun 18, 2008 at 01:23:20PM +0200, Christophe Combelles wrote:
Hi Christian,
let's take a real package as an example (on which I recently did some merges)
CHANGES.txt on the trunk: http://svn.zope.org/zope.app.container/trunk/CHANGES.txt?rev=87370
CHANGES.txt on the 3.5 branch: http://svn.zope.org/zope.app.container/branches/3.5/CHANGES.txt?rev=87428
Given what you said, what should these files look like?
*Almost* as they look like now, except that the changes from 3.5.1+ on the trunk would be visible as a change to 3.6. It would have only one entry for 3.5 which would be 3.5.0; and probably the pre-releases leading to the stable 3.5.0.
Something like this? http://svn.zope.org/zope.app.container/trunk/CHANGES.txt?rev=87519 It allows to have a smaller changes.txt, but I see just one problem: imagine there is an early bugfix in 3.5.1, before 3.6.0 is released. If I understand well, the 3.5.1 bugfix should appear later in the trunk in the 3.6.0 section, but not in 3.5 ? The risk is that people will think the bug is fixed in 3.6.0 and not in the 3.5 branch.
Christian
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. -Fred -- Fred L. Drake, Jr. <fdrake at gmail.com> "Chaos is the score upon which reality is written." --Henry Miller
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.) I guess that merging release notes automatically would actually be easier in the format that I proposed ... Christian -- Christian Theune · ct@gocept.com gocept gmbh & co. kg · forsterstraße 29 · 06112 halle (saale) · germany http://gocept.com · tel +49 345 1229889 7 · fax +49 345 1229889 1 Zope and Plone consulting and development
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
On Jun 18, 2008, at 19:00 , yuppie wrote:
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.
That's not the only audience. I as a developer consult CHANGES.txt to (hopefully) find *all* changes on the respective branch or on the trunk that have flowed into it until now. I'm not sure what you're saying in that last paragraph. Copying a change history isn't needed when you're diligent about updating the change log whenever you make actual trunk changes. jens
Jens Vagelpohl wrote:
On Jun 18, 2008, at 19:00 , yuppie wrote:
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.
That's not the only audience. I as a developer consult CHANGES.txt to (hopefully) find *all* changes on the respective branch or on the trunk that have flowed into it until now.
Can't developers use the subversion history?
I'm not sure what you're saying in that last paragraph. Copying a change history isn't needed when you're diligent about updating the change log whenever you make actual trunk changes.
Sorry. I was referring to the current Zope 2 (and CMF) policy: "Note that you don't need to note the fix in the CHANGES.txt on the trunk if you don't want to. At the time a new feature release is made, we merge the items in CHANGES.txt from the trunk and current release branch so that for any given release it notes the actual changes as of that release." http://www.zope.org/DevHome/Subversion/ZopeDevelopmentProcess Cheers, Yuppie
On Wed, Jun 18, 2008 at 1:27 PM, yuppie <y.2008@wcm-solutions.de> wrote:
Sorry. I was referring to the current Zope 2 (and CMF) policy:
"Note that you don't need to note the fix in the CHANGES.txt on the trunk if you don't want to. At the time a new feature release is made, we merge the items in CHANGES.txt from the trunk and current release branch so that for any given release it notes the actual changes as of that release." http://www.zope.org/DevHome/Subversion/ZopeDevelopmentProcess
Egads. No wonder there was a question about what's the right thing. That's not it. -Fred -- Fred L. Drake, Jr. <fdrake at gmail.com> "Chaos is the score upon which reality is written." --Henry Miller
On Jun 18, 2008, at 19:32 , Fred Drake wrote:
On Wed, Jun 18, 2008 at 1:27 PM, yuppie <y.2008@wcm-solutions.de> wrote:
Sorry. I was referring to the current Zope 2 (and CMF) policy:
"Note that you don't need to note the fix in the CHANGES.txt on the trunk if you don't want to. At the time a new feature release is made, we merge the items in CHANGES.txt from the trunk and current release branch so that for any given release it notes the actual changes as of that release." http://www.zope.org/DevHome/Subversion/ZopeDevelopmentProcess
Egads. No wonder there was a question about what's the right thing.
That's not it.
Considering situations where there's more than one release branch that "merging" process becomes quite tedious. So I concur, I'd rather get rid of that scheme. jens
On Jun 18, 2008, at 19:27 , yuppie wrote:
That's not the only audience. I as a developer consult CHANGES.txt to (hopefully) find *all* changes on the respective branch or on the trunk that have flowed into it until now.
Can't developers use the subversion history?
It's much quicker to look at the change log, and when you work with tarballs there's no subversion history. So no, that's not a good "replacement" for my uses.
I'm not sure what you're saying in that last paragraph. Copying a change history isn't needed when you're diligent about updating the change log whenever you make actual trunk changes.
Sorry. I was referring to the current Zope 2 (and CMF) policy:
"Note that you don't need to note the fix in the CHANGES.txt on the trunk if you don't want to. At the time a new feature release is made, we merge the items in CHANGES.txt from the trunk and current release branch so that for any given release it notes the actual changes as of that release." http://www.zope.org/DevHome/Subversion/ZopeDevelopmentProcess
I think I have done some of that merging once in a while, but always in a haphazard fashion and did not know about the URL you provided. I personally dislike that, and would strongly favor noting every change on the trunk as it is checked in, just like you would do on the branch. jens
Hi! Jens Vagelpohl wrote:
On Jun 18, 2008, at 19:27 , yuppie wrote:
That's not the only audience. I as a developer consult CHANGES.txt to (hopefully) find *all* changes on the respective branch or on the trunk that have flowed into it until now.
Can't developers use the subversion history?
It's much quicker to look at the change log, and when you work with tarballs there's no subversion history. So no, that's not a good "replacement" for my uses.
Nobody proposes to make releases without a complete CHANGES.txt. In a released version you should always find all changes. The only real difference between current and proposed policy is how the change notes are ordered and grouped. The current Zope 2 policy doesn't make sure the change history of unreleased versions is complete. But that's no essential part of that policy. And working with unreleased versions you might use subversion anyway.
I'm not sure what you're saying in that last paragraph. Copying a change history isn't needed when you're diligent about updating the change log whenever you make actual trunk changes.
Sorry. I was referring to the current Zope 2 (and CMF) policy:
"Note that you don't need to note the fix in the CHANGES.txt on the trunk if you don't want to. At the time a new feature release is made, we merge the items in CHANGES.txt from the trunk and current release branch so that for any given release it notes the actual changes as of that release." http://www.zope.org/DevHome/Subversion/ZopeDevelopmentProcess
I think I have done some of that merging once in a while, but always in a haphazard fashion and did not know about the URL you provided. I personally dislike that, and would strongly favor noting every change on the trunk as it is checked in, just like you would do on the branch.
Well. I don't like the "if you don't want to" part of the current policy because it just creates chaos. If everybody follows the same policy, the merging is not that much work. Cheers, Yuppie
On Jun 18, 2008, at 20:30 , yuppie wrote:
The current Zope 2 policy doesn't make sure the change history of unreleased versions is complete. But that's no essential part of that policy. And working with unreleased versions you might use subversion anyway.
See, I think that's bad. The change log should reflect all changes, be it in a released version or from Subversion. Or be it a release branch or the trunk.
"Note that you don't need to note the fix in the CHANGES.txt on the trunk if you don't want to. At the time a new feature release is made, we merge the items in CHANGES.txt from the trunk and current release branch so that for any given release it notes the actual changes as of that release." http://www.zope.org/DevHome/Subversion/ZopeDevelopmentProcess I think I have done some of that merging once in a while, but always in a haphazard fashion and did not know about the URL you provided. I personally dislike that, and would strongly favor noting every change on the trunk as it is checked in, just like you would do on the branch.
Well. I don't like the "if you don't want to" part of the current policy because it just creates chaos. If everybody follows the same policy, the merging is not that much work.
It is much work if you have more than a single release branch. With the CMF, we have had times recently where stuff is updated on up to 3 branches plus trunk. Having to consult all those branches to synthesize the change log on the trunk is a major PITA and I don't see how that can be sane. jens
On Thu, Jun 19, 2008 at 09:08:54AM +0200, Jens Vagelpohl wrote:
On Jun 18, 2008, at 20:30 , yuppie wrote:
The current Zope 2 policy doesn't make sure the change history of unreleased versions is complete. But that's no essential part of that policy. And working with unreleased versions you might use subversion anyway.
See, I think that's bad. The change log should reflect all changes, be it in a released version or from Subversion. Or be it a release branch or the trunk.
Please note that our use of the CHANGES.txt is more that of `release notes` meaning it should have a more condensed form of what would be available using `svn log`. I wouldn't see the point maintaining a text file that has identical information that could be retrieved from SVN. The condensed form is intended to provide better usability than to wade through hundreds of commits. Christian -- Christian Theune · ct@gocept.com gocept gmbh & co. kg · forsterstraße 29 · 06112 halle (saale) · germany http://gocept.com · tel +49 345 1229889 7 · fax +49 345 1229889 1 Zope and Plone consulting and development
On Jun 19, 2008, at 09:51 , Christian Theune wrote:
On Thu, Jun 19, 2008 at 09:08:54AM +0200, Jens Vagelpohl wrote:
See, I think that's bad. The change log should reflect all changes, be it in a released version or from Subversion. Or be it a release branch or the trunk.
Please note that our use of the CHANGES.txt is more that of `release notes` meaning it should have a more condensed form of what would be available using `svn log`. I wouldn't see the point maintaining a text file that has identical information that could be retrieved from SVN.
The condensed form is intended to provide better usability than to wade through hundreds of commits.
I meant the same thing, yes. The main point was simply that all branches and the trunk should always have a complete change log and no merging or picking stuff from one or more branches to get to the complete change history should be necessary. jens
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@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
On Jun 19, 2008, at 12:32 , yuppie wrote:
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.
I don't think that assumption holds true. Again, using the CMF as an example, there were times when we had 3 release branches. I don't want to start a discussion why that was or how to prevent that from happening, I'm just saying it's not correct to say you always have just one maintenance branch. And that's where all those fancy schemes fall down. jens
Jens Vagelpohl wrote:
On Jun 19, 2008, at 12:32 , yuppie wrote:
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.
I don't think that assumption holds true. Again, using the CMF as an example, there were times when we had 3 release branches. I don't want to start a discussion why that was or how to prevent that from happening, I'm just saying it's not correct to say you always have just one maintenance branch. And that's where all those fancy schemes fall down.
You did get me wrong :( I tried to make a distinction between the current maintenance branch (= branch for maintaining the *current* release) and old maintenance branches (= branches for maintaining older release). If someone knows better terms, please let me know. The *current* version of CMF is 2.1.1. If you release CMF 1.6.5 with some backports from the 2.1 branch, it will not become the *current* CMF release. As soon as CMF 2.2.0 is released it will become the current release and the 2.2 branch the current maintenance branch. No? Cheers, Yuppie
On Jun 19, 2008, at 13:36 , yuppie wrote:
Jens Vagelpohl wrote:
On Jun 19, 2008, at 12:32 , yuppie wrote:
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. I don't think that assumption holds true. Again, using the CMF as an example, there were times when we had 3 release branches. I don't want to start a discussion why that was or how to prevent that from happening, I'm just saying it's not correct to say you always have just one maintenance branch. And that's where all those fancy schemes fall down.
You did get me wrong :(
I tried to make a distinction between the current maintenance branch (= branch for maintaining the *current* release) and old maintenance branches (= branches for maintaining older release). If someone knows better terms, please let me know.
The *current* version of CMF is 2.1.1. If you release CMF 1.6.5 with some backports from the 2.1 branch, it will not become the *current* CMF release. As soon as CMF 2.2.0 is released it will become the current release and the 2.2 branch the current maintenance branch. No?
Sorry, you're right, I realized I did get you wrong after sending my reply. As always ;-) I do have one last question, though (unless I misunderstand something, again): In my understanding, we're now down to a single policy difference, about the point in time when you want the trunk CHANGES file updated. You're still saying it will only ever be fully updated when the current release branch changes are merged in, probably just before creating a new release branch, right? I still don't see an advantage in pushing this CHANGES maintenance on the trunk to the release manager as opposed to every developer maintaining it concurrently with the release branch CHANGES file. I personally would much rather see all changes that are on the trunk to be reflected in its CHANGES file at all times. jens
Jens Vagelpohl wrote:
On Jun 19, 2008, at 13:36 , yuppie wrote:
Jens Vagelpohl wrote:
On Jun 19, 2008, at 12:32 , yuppie wrote:
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. I don't think that assumption holds true. Again, using the CMF as an example, there were times when we had 3 release branches. I don't want to start a discussion why that was or how to prevent that from happening, I'm just saying it's not correct to say you always have just one maintenance branch. And that's where all those fancy schemes fall down.
You did get me wrong :(
I tried to make a distinction between the current maintenance branch (= branch for maintaining the *current* release) and old maintenance branches (= branches for maintaining older release). If someone knows better terms, please let me know.
The *current* version of CMF is 2.1.1. If you release CMF 1.6.5 with some backports from the 2.1 branch, it will not become the *current* CMF release. As soon as CMF 2.2.0 is released it will become the current release and the 2.2 branch the current maintenance branch. No?
Sorry, you're right, I realized I did get you wrong after sending my reply. As always ;-)
I do have one last question, though (unless I misunderstand something, again): In my understanding, we're now down to a single policy difference, about the point in time when you want the trunk CHANGES file updated. You're still saying it will only ever be fully updated when the current release branch changes are merged in, probably just before creating a new release branch, right?
And you did get me wrong again ;) My first mail today started with these sentences:
Second try. My first response to this lead to a discussion about immediate or delayed syncing of CHANGES.txt. That was not my point.
I'm fine with keeping CHANGES.txt on the trunk always up to date. The policy difference I'd like to discuss is something completely different: How are the change notes grouped on the trunk? The proposed new policy is to put everything in one big section: Forward-ports from the current maintenance branch and "trunk only" changes are mixed together. CHANGES.txt just shows the difference between pre-releases of major versions. The old policy, which I like better in this point, solves this differently: Change notes for forward-ports are grouped by release versions from the current maintenance branch. CHANGES.txt helps you to figure out differences between any two versions in the series of 'current' versions, not only between major versions. Note that the policies are the same for CHANGES.txt files on all branches. They are only different for CHANGES.txt on the trunk. Cheers, Yuppie
On Wed, Jun 18, 2008 at 04:21:08PM +0200, Christophe Combelles wrote:
Something like this? http://svn.zope.org/zope.app.container/trunk/CHANGES.txt?rev=87519
Yup. -- Christian Theune · ct@gocept.com gocept gmbh & co. kg · forsterstraße 29 · 06112 halle (saale) · germany http://gocept.com · tel +49 345 1229889 7 · fax +49 345 1229889 1 Zope and Plone consulting and development
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
On Wed, Jun 18, 2008 at 10:38:51PM +0200, Martijn Faassen wrote:
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).
I do not consider stuff within a version do be ordered by a given criterion, except maybe readability, so during development I tend to add stuff to the top, because it's easier to reach. Sometimes I add it in the middle because it seems easier to read. So, I'm not concerned about the order that people add to those sets. -- Christian Theune · ct@gocept.com gocept gmbh & co. kg · forsterstraße 29 · 06112 halle (saale) · germany http://gocept.com · tel +49 345 1229889 7 · fax +49 345 1229889 1 Zope and Plone consulting and development
Hi there, On Wed, Jun 18, 2008 at 11:02 PM, Christian Theune <ct@gocept.com> wrote: [snip]
I do not consider stuff within a version do be ordered by a given criterion, except maybe readability, so during development I tend to add stuff to the top, because it's easier to reach. Sometimes I add it in the middle because it seems easier to read.
I think the primarily criterion should be readability (if order matters to improve readability), and the secondary criterion should be time when the change was add (if it doesn't matter for readability). Couldn't we standardize on something? I consider there two be two situations: * you make a change and add something to the change log. Ordering is by time (from top or bottom, not both ways :) * you change the changelog for readability, grouping related items together. Of course sometimes the first may lead to the second. Ordering can be changed; you're refactoring the order, after all. Compare with code: when refactoring it's okay to change the order of code too if it improves readability, when doing normal fixes or tweaks it's generally not the right thing to do, but sometimes a refactoring happens because of a bugfix.
So, I'm not concerned about the order that people add to those sets.
If I know I normally only have to check the bottom (or top) of each section to see whether something got added since last time I checked, there's less chance I'll miss it and make a mistake. It's not a major point, but it'd be nice if everybody acted more or less the same instead of changelog sections growing from both ends. Regards, Martijn
Hi, On Wed, Jun 18, 2008 at 11:09:17PM +0200, Martijn Faassen wrote:
[...] If I know I normally only have to check the bottom (or top) of each section to see whether something got added since last time I checked, there's less chance I'll miss it and make a mistake.
It's not a major point, but it'd be nice if everybody acted more or less the same instead of changelog sections growing from both ends.
Sure. It's not the major target group either. During development I tend to use SVN to find the changes since last time I looked. Between releases the ordering is mostly important on the release level, not inside as releases are the atomic step for people to update to. My preference would be to have more important changes first. Christian -- Christian Theune · ct@gocept.com gocept gmbh & co. kg · forsterstraße 29 · 06112 halle (saale) · germany http://gocept.com · tel +49 345 1229889 7 · fax +49 345 1229889 1 Zope and Plone consulting and development
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Christian Theune wrote:
Hi,
On Wed, Jun 18, 2008 at 11:09:17PM +0200, Martijn Faassen wrote:
[...] If I know I normally only have to check the bottom (or top) of each section to see whether something got added since last time I checked, there's less chance I'll miss it and make a mistake.
It's not a major point, but it'd be nice if everybody acted more or less the same instead of changelog sections growing from both ends.
Sure. It's not the major target group either. During development I tend to use SVN to find the changes since last time I looked.
Between releases the ordering is mostly important on the release level, not inside as releases are the atomic step for people to update to.
My preference would be to have more important changes first.
Please don't make it a judgement call: keep it time-descending order, just like the releases. Among other things, this makes merge conflicts more obvious, and easier to to fix. Tres. - -- =================================================================== Tres Seaver +1 540-429-0999 tseaver@palladion.com Palladion Software "Excellence by Design" http://palladion.com -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.6 (GNU/Linux) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org iD8DBQFIWkxr+gerLs4ltQ4RApoNAKC6VhA15+0d5DbVsPiukfs6rnYKEgCgx9eX 91xqaqN1cPcy0ZTI4ed+QX0= =7VXA -----END PGP SIGNATURE-----
Tres Seaver wrote:
Christian Theune wrote: [snip]
My preference would be to have more important changes first.
Please don't make it a judgement call: keep it time-descending order, just like the releases. Among other things, this makes merge conflicts more obvious, and easier to to fix.
With time-descending order you mean add more recent fixes to the top of the section, right? Where 'section' is probably the 'bug fixes' or 'features' section per release. Regards, Martijn
On Jun 19, 2008, at 14:41 , Martijn Faassen wrote:
Tres Seaver wrote:
Christian Theune wrote: [snip]
My preference would be to have more important changes first. Please don't make it a judgement call: keep it time-descending order, just like the releases. Among other things, this makes merge conflicts more obvious, and easier to to fix.
With time-descending order you mean add more recent fixes to the top of the section, right? Where 'section' is probably the 'bug fixes' or 'features' section per release.
I'd vote for the simple time-based order with the newest entries at the top as well. Matter of fact, unless there's such a large amount of entries for a release that you need more order, I would do away with sub-sections like "bug fixes", "features" etc as well. I'd put a simple prefix at the front: - BUG: Fixed behavior of foobar widget - FEATURE: Added new bar widget for handling baz values. - ... jens
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Martijn Faassen wrote:
Tres Seaver wrote:
Christian Theune wrote: [snip]
My preference would be to have more important changes first. Please don't make it a judgement call: keep it time-descending order, just like the releases. Among other things, this makes merge conflicts more obvious, and easier to to fix.
With time-descending order you mean add more recent fixes to the top of the section, right? Where 'section' is probably the 'bug fixes' or 'features' section per release.
Right. If we were really strict about the existing policy, then bug fixes wouldn't be recorded on the trunk, only features, and there would never be features added on maintenance / release branches. That policy also strongly suggests doing the initial fix on the oldest maintained branch which has the bug, and then forward-porting it to newer branches and the trunk. Specifically, we don't "backport" bug fixes, we "forward-port" them. I've found that doing the fixes in that order has two advantages: - Fixing it on the oldest branch first makes for a better diagnostic mode, with fewer assumptions about the code (because one isn't working in it regularly). - The fix stays minimal / conservative, because we don't make arbitrary cleanups / rearrangements to the code on the branches. - It is usually much easier to merge the minimal fix forward, even if a later branch has been tidied / refactored, than to merge backward. If we change the policy to record all bugfixes in the trunk's changelog, then I would still advocate grouping them: it makes the release manager's job simpler, since the groupings are more informative in an announcement. Tres. - -- =================================================================== Tres Seaver +1 540-429-0999 tseaver@palladion.com Palladion Software "Excellence by Design" http://palladion.com -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.6 (GNU/Linux) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org iD8DBQFIWluv+gerLs4ltQ4RAkQXAJ98umZ2EFMbbvH3xYobJlwhDReWSQCfUGwc m991vofVbLRHJFrP+1KEj9c= =/4Lz -----END PGP SIGNATURE-----
participants (7)
-
Christian Theune -
Christophe Combelles -
Fred Drake -
Jens Vagelpohl -
Martijn Faassen -
Tres Seaver -
yuppie