Our release notes process is quite straight forward. New release notes go to RELEASE-NOTES file, and after releasing a new major version, they get moved into HISTORY and a clean RELEASE-NOTES is created. The linear history is easily preserved this way.
However, there's a kind of changes which doesn't have an exact addition version. Changes that deserve backporting are done into trunk, then backported by merging with the supported releases. The RELEASE-NOTES of those versions are updated in a "Changes since xyz" heading.
However, it is not clear where that release notes should go on the HISTORY file. Specially since it is no longer linear. Currently, we could have a revision go into 1.15.6, 1.16.1 and 1.17.0. At which point should it be placed?
Old versions (up to 1.5.x) do have entries for updates in HISTORY file, and also 1.13.x, but that's it.
We don't seem to be maintaining it, as brought up in r72587.
What should be the procedure when backporting? * When merging to an earlier release, the RELEASE-NOTES go there, and is added into trunk HISTORY file at the same time.
* When merging to an earlier release, the RELEASE-NOTES go there. On release, the new section is added as a whole on the trunk HISTORY.
* We don't keep HISTORY for release updates. Changes get an entry inside the branch RELEASE-NOTES, but also inside the trunk one. It is shipped as a fix on the next major, even if it was also fixed in some minor in-between.
The last one is the lazier one, and completely avoids the on-which-version issues. However, it can't cope with problems that are only fixed in the branch (eg. a minor fix for a feature that was completely rewritten in trunk). It also delusions users as giving fixes that they (should) already have.
I would prefer one of the other two, and perhaps give a common entry on HISTORY "Bug fixes in 1.15.x and 1.16.y".
Opinions?
On 08/11/10 04:28, Platonides wrote:
What should be the procedure when backporting?
- When merging to an earlier release, the RELEASE-NOTES go there,
and is added into trunk HISTORY file at the same time.
It's hard enough to get people to update one file.
- When merging to an earlier release, the RELEASE-NOTES go there.
On release, the new section is added as a whole on the trunk HISTORY.
This is more or less what I do at the moment. When I create a new major version, I update the HISTORY file in the new branch, copying in changes from the RELEASE-NOTES in the old branch.
If we have a 1.16.x release sequence and a 1.15.x release sequence, then changes that are backported to 1.15.x are usually also backported to 1.16.x, so the RELEASE-NOTES entry will be in both of them. So the HISTORY file in the 1.16.x branch contains changes made to the 1.15.x branch before the branch point, and the RELEASE-NOTES file contains changes made after it.
-- Tim Starling
Tim Starling wrote:
On 08/11/10 04:28, Platonides wrote:
- When merging to an earlier release, the RELEASE-NOTES go there.
On release, the new section is added as a whole on the trunk HISTORY.
This is more or less what I do at the moment. When I create a new major version, I update the HISTORY file in the new branch, copying in changes from the RELEASE-NOTES in the old branch.
If we have a 1.16.x release sequence and a 1.15.x release sequence, then changes that are backported to 1.15.x are usually also backported to 1.16.x, so the RELEASE-NOTES entry will be in both of them. So the HISTORY file in the 1.16.x branch contains changes made to the 1.15.x branch before the branch point, and the RELEASE-NOTES file contains changes made after it.
-- Tim Starling
The question was in the line of what to do with *trunk* HISTORY, for which two older releases would include the fix. Thus the idea of a "Bug fixes in 1.15.6 and 1.16.1" headline.
On 08/11/10 09:58, Platonides wrote:
The question was in the line of what to do with *trunk* HISTORY, for which two older releases would include the fix. Thus the idea of a "Bug fixes in 1.15.6 and 1.16.1" headline.
The RELEASE-NOTES for 1.16.x will be copied into trunk immediately before the branch point for 1.17.x. So after the branch, such a change will have a HISTORY entry for 1.16.1 and not 1.15.6.
I don't think it's worthwhile updating the HISTORY in trunk in between major releases, since the HISTORY file is intended for users of tarball releases.
Sometimes people do try to add things to the HISTORY file in between branch points, resulting in it containing a random selection of backported changes. Rather than pick through it and try to work out what's missing, I found it easier to delete the most recent sections and re-add them by copying from the branch RELEASE-NOTES.
-- Tim Starling
wikitech-l@lists.wikimedia.org