Open Stack

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.

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