Open Stack

On 8 Jun 2016, at 11:13, Doug Hellmann wrote:

> tl;dr: The switch from pre-versioning to post-versioning means that
> sometimes master appears to be older than stable/$previous, so we
> merge "final" tags from stable/$previous into master to make up for
> it. This introduces versions into the history of master that aren't
> *really* there, but git sees them and so does reno. That, in turn,
> means that the release notes generated from master may place some
> notes in the wrong version, suggesting that something happened
> sooner than it did. I propose that we stop merging tags, and instead
> introduce a new tag on master after we create a branch to ensure
> that the version number there is always higher than stable/$previous.
>
>
> Background
> ----------
>
> Over the last year or so we've switched from pre-versioning (declaring
> versions in setup.cfg) to post-versioning (relying solely on git
> tags for versions). This made the release process simpler, because
> we didn't need to worry about synchronizing the change of version
> strings within setup.cfg as we created our branches. A side-effect,
> though, is that the version from which we tag appears on both
> branches. That means that stable/$previous and master both have the
> same version for some period of time, and then stable/$previous
> receives a final tag and has a version newer than master. To
> compensate, we merge that final tag from stable/$previous into
> master (taking only the tag, without any of the code changes), so
> that master again has the same version.
>
>
> The Problem
> -----------
>
> The tag may be merged into master after other changes have landed
> in master but not stable/$previous, and if those changes include
> release notes then reno will associate them with the newly merged
> tag, rather than the correct version number.
>
> Here's an example I have been using to test reno. In it, 3 separate
> reno notes are created on two branches. Note 1 is on master when
> it is tagged 1.0.0. Then master is branched and note 2 is added to
> the branch and tagged 1.1.0. Then the tag is merged into master and
> note 3 is added.
>
>   * af93946 (HEAD -> master, tag: 2.0.0) add slug-0000000000000003.yaml
>   * f78d1a2 add ignore-2.txt
>   *   4502dbd merge 1.1.0 tag into master
>   |\
>   | * bf50a97 (tag: 1.1.0, test_merge_tags) add slug-0000000000000002.yaml
>   * | 1e4d846 add ignore-1.txt
>   |/
>   * 9f481a9 (tag: 1.0.0) add slug-0000000000000001.yaml
>
> Before the tag is applied to note 3, it appears to be part of 1.1.0,
> even though it is not from the branch where that version was created
> and the version 1.1.0 is included in the release notes for master,
> even though that version should not really be a part of that series.
>
> Technically reno is doing the right thing, because even "git describe"
> honors the merged tag and treats commit f78d1a2 as 1.1.0-4-gaf93946.
> So because we've merged the version number into a different series
> branch, that version becomes part of that series.
>
>
> The Proposal
> ------------
>
> We should stop merging tags between branches, at all. Then our git
> branches will be nice and linear, without merges, and reno will
> associate the correct version number with each note.
>
> To compensate for the fact that master will have a lower version
> number after the branch, we can introduce a new alpha tag on master
> to raise its version. So, after creating stable/$series from version
> X.0.0.0rc1, we would tag the next commit on master with X+1.0.0.0a1.
> All subsequent commits on master would then be considered to be
> part of the X+1.0.0 series.

This seems to go back to the essence of pre-versioning. Instead of updating a string in a file, you've updated it as a tag. You've still got the coordination issues at release to deal with (when and what to tag) and the issue of knowing what the next release is before you've landed any patches that will be in that release.

Isn't the reason that the branch is merged back in because otherwise per can't generate a valid version number? You've "solved" that by hiding the release version number behind the new *a1 tag. Therefore, for any commit on the master branch, the only ancestor commits that are tagged will have the *a1 tags, and the actual release tags will never be reachable by walking up parent commits (assuming there is at least one commit on a release branch, which seems normal).



>
> Libraries and other projects that follow the cycle-with-intermediary
> release model won't need this treatment, because we're not using
> alpha or beta versions for them and they are tagged more often than
> the projects following the cycle-with-milestones model.
>
>
> Possible Issues
> ---------------
>
> We will be moving back to a situation where we have to orchestrate
> multiple operations when we create branches. Adding an extra tag
> isn't a lot of work, though, and it doesn't really matter what the
> commit is that gets the tag, so if there's nothing on master beyond
> the point where a branch needs to be created we can add a minor
> change somewhere just to have something to tag.
>
> fungi pointed out that if we backport anything by using a fast-forward
> merge from master to stable/$previous, we will pull the newer version
> number back into the older series. We already have that issue,
> today, though, for anything backported after the first milestone.
> So while we're shrinking the safe window period, this is not a new
> problem.
>
> Some cycle-with-milestone projects may not merge commits into master
> very soon after their branches are created. We can address that by
> waiting, or by introducing a small commit just for the purpose of
> having something to tag.
>
>
> Alternatives
> ------------
>
> Do nothing and live with some of our early release notes in a version
> being "not quite right." I don't consider this acceptable.
>
> Switch back to pre-versioning. We dropped this for a good reason,
> it makes synchronizing all of the actions needed to create a release
> branch a real hassle.
>
>
> If everyone agrees that this is a reasonable change to make, I will
> update our release documentation and do the work to turn of the tag
> merging job in project-config.
>
> Doug
>
> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 801 bytes
Desc: OpenPGP digital signature
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20160608/1410dbc4/attachment.pgp>