Skip to content

Branching Model

Jump to bottom Edit New page
Sandro Mathys edited this page Dec 16, 2015 · 3 revisions

This page explains the branching model for the projects.

MidoNet

There are following types of branches:

Development: contains new features and bug fixes in active development. Devs work mainly here and are responsible to set the fixVersion field in JIRA according to the version currently committed here.

  • Naming Scheme: master
  • Version in source: vX.Y-SNAPSHOT

Staging: created after a "feature freeze" it contains sufficient features required for a given version. This code will be QA'd and stabilized with bug fixes until it's approved for release. After releasing, the branch is considered maintenance and must only receive bug fixes explicitly requested by Product through the fixVersion field of JIRA issues. At any point Product may request to release a new patch version vX.Y.(Z+1) containing the new bug fixes added. NO NEW FEATURES are allowed in a staging/* branch.

  • Naming scheme: staging/vX.Y
    • Must be branched off master
    • RCs will be tagged on this branch as vX.Y.Z-rcN (N starting at 0, ++ on every new RC)
  • Version in source: vX.Y-SNAPSHOT

Releases: Code has successfully passed the QA phase and released. After a release is complete, the stable/vX.Y.Z branch is closed and will not receive any new commits.

  • Naming scheme: stable/vX.Y.Z
    • Must be branched off staging/vX.Y after desired bug fixes are merged.
  • Version in source: vX.Y.Z

Hotfixes: meant to address a mission-critical issue found found in a released version without waiting for a patch release that would require a full QA cycle. For this purpose, we use a new branch off the corresponding stable/ branch. This allows maintaining the original released version untouched, while being able to provide custom hotfixes for different users. Hotfixes are custom-built and, as releases, remain closed after released. Hotfixes must be backported into relevant maintenance branches for their inclusion in ordinary patch releases.

  • Naming scheme: hotfix/vX.Y.Z.<id>
    • Must be branched off stable/vX.Y.Z
  • Version in source: vX.Y.Z.<id>

Tagging

Tags are applied during the stabilization period and at the final release.

For release candidates tag the new RC as staging/vX.Y.Z-rcN:

  • git checkout <SHA>
  • git tag -a vX.Y.Z-rcN
  • git push origin vX.Y.Z-rcN

For the final release:

  • git checkout <SHA>
  • git tag -a vX.Y.Z
  • git push origin vX.Y.Z

TODO: Hotfix?

Version Numbers

The versioning model of MidoNet follows semantic versioning, but this may change in the near future.

Visual representation of the development & release cycle

NOTE: this graph is out of date, we'll be fixing it soon. The releases and hotfixes are made in BRANCHES, not TAGs.

MidoNet Release and Dev Cycle

  • Red # bugfix * Green = change to version number committed in repo * Yellow = feature freeze point * Red-on-yellow = hotfi * Bold = branch * Italics tag

MidoNet Client

Python MidoNet Client (PMC henceforth) is integrated inside the MidoNet and follows the same policies than previous section. The only difference is that for each commit submitted into MidoNet, a Jenkins job will rsync into a target mirror repo.

PMC is a dependency of Neutron MidoNet plugin, and its setup.py script needs to be accessible from a root directory. This is the reason of the target mirror repo. No pull request or patch review will be allowed directly in target mirror repo.

Neutron MidoNet Plugin

The branching model of the plugin closely follows the OpenStack branching model.

MidoNet Plugin master branch will tip always on the Neutron's master branch (defined on its requirements.txt file to detect inmediate changes and be able to be released right after an OpenStack release.

In the same time the upstream OpenStack has a release and a stable branch is cut, a matching branch is cut in the plugin project as well with the same name stable/xxxx. This branch keeps track of eventual changes in Neutron's interfaces and let us detect incompatibilities

Also, MidoNet plugin fixes his bugs against the last tagged/packaged version of OpenStack. The branch that pins the last tagged version it have the name (releases/xxxx).

Once a new tag is released in the maintain release, any change done in stable/xxx is the dumped to releases/xxx, and a new version of the plugin is released to add these Neutron bugfixes.

Tagging

Tags are created for every release of the plugin always in the 'releases/xxx' branch!

Version Numbers

Please refer to Packaging#neutron-midonet-plugin to find the version number format.

How to release

Configure git and requirements

Without the details of which tag to create, first you need to know the requirements to create a tag.

networking-midonet project only accepts signed tags. That means you need to have a GPG key and a proper git configuration like this in your $HOME/.gitconfig file:

[user]
    name = Jaume Devesa
    email = devvesa@gmail.com
    signingkey = CDCEB129

The signing key option is the one that Git will use to sign the tag.

Also, you need to be part of the networking-midonet-release group on gerrit

Release candidate of a new major version

Let's suppose we are ready to do a release candidate for the current master branch. In this case, we are going to create the tag over the master branch of the project.

networking-midonet implements functionallity of two projects:

And uses the same version numbers like 2015.1 in its first two digits of the version. It will always be released after these projects and hence, it should pin its versions. So before to create the release candidate, make sure that requirements.txt file content pins to the same tag version you pretend to release on neutron and neutron-lbaas. For instance, now we want to create the version 2015.1.0-rc1, so this content is correct:

Pinned versions

If, instead of @2015.1.0#egg=neutron you find @master#egg=neutron your code is probably incorrect because new code has been added that will be part of 2015.2.0.

To create the tag, you have to do the following

  $ git tag -s 2015.1.0-rc1 -m "Release candidate 1 for Kilo"
  $ git push gerrit 2015.1.0-rc1

That will push the tag on GitHub and the 'egg' file in pypi. Note that we don't use the rc0 tag.

New major version

Major release version is the one that give us more work to do. We have to:

Create the tag

In the master branch, create the tag and push it:

 $ git tag -s 2015.1.0 -m "Releasing Kilo"
 $ git push gerrit 2015.1.0

That's enough for the tag.

Create the release/xxx branch

Release branch will have the bugfixes found in the plugin and will pin into the last released version of the Neutron, Neutron Lbaas and MidoNet projects.

To do so, create a release branch:

  $ git checkout -b release/kilo

Create the reference on gerrit:

  $ git push gerrit HEAD:refs/heads/release/kilo

Then edit the PKG-INFO file and make sure that the Version tag increments in one value the last digit. In this example, to 2015.1.1:

...e/networking-midonet (release/kilo) > cat PKG-INFO | grep Version
Version: 2015.1.1

Edit the setup.cfg file and make sure the version tag is incremented in one value too in the last digit:

...e/networking-midonet (release/kilo) > cat setup.cfg | grep version
version = 2015.1.1

Edit (if you need to edit it) the requirements.txt file and make sure their are referencing to the last tag of neutron and neutron-lbaas project. In this case 2015.1.0

  ...e/networking-midonet (release/kilo) > cat requirements.txt | grep neutron
-e git://git.openstack.org/openstack/neutron.git@2015.1.0#egg=neutron
-e git://git.openstack.org/openstack/neutron-lbaas.git@2015.1.0#egg=neutron-lbaas
...e/networking-midonet (release/kilo) >

Edit the file devstack/settings and make sure the MidoNet branch is pinned to the last version released of MidoNet:

...e/networking-midonet (release/kilo) > cat devstack/settings | grep MIDONET_BRANCH
MIDONET_BRANCH=${MIDONET_BRANCH:-stable/v2015.03}

Push the branch:

  $ git review release/kilo
Create the stable/xxx branch

Stable branch will take care of keep in sync with neutron's and neutron-lbaas' stable/kilo branches and find immediate conflicts with our code. This branch should not have new code unless we detect one of these conflicts.

To do so, create a stable branch:

  $ git checkout -b stable/kilo

Create the reference on gerrit:

  $ git push gerrit HEAD:refs/heads/stable/kilo

Then edit the PKG-INFO file and make sure that the Version tag increments in one value the last digit. In this example, to 2015.1.1:

...e/networking-midonet (stable/kilo) > cat PKG-INFO | grep Version
Version: 2015.1.1

Edit the setup.cfg file and make sure the version tag is incremented in one value too in the last digit:

...e/networking-midonet (stable/kilo) > cat setup.cfg | grep version
version = 2015.1.1

Edit the requirements.txt file and make sure their are referencing to the maintain branches of neutron and neutron-lbaas project. In this case stable/kilo

  ...e/networking-midonet (stable/kilo) > cat requirements.txt | grep neutron
-e git://git.openstack.org/openstack/neutron.git@stable/kilo#egg=neutron
-e git://git.openstack.org/openstack/neutron-lbaas.git@stable/kilo#egg=neutron-lbaas
...e/networking-midonet (stable/kilo) >

Edit the file devstack/settings and make sure the MidoNet branch is pinned to the last version released of MidoNet:

...e/networking-midonet (stable/kilo) > cat devstack/settings | grep MIDONET_BRANCH
MIDONET_BRANCH=${MIDONET_BRANCH:-stable/v2015.03}

Push the branch:

  $ git review stable/kilo
Update the master branch to new release

Now is time to move on in master to be on the edge development of neutron and neutron-lbaas. Follow the steps:

Make sure you are in master:

  $ git checkout master

Then edit the PKG-INFO file and make sure that the Version tag increments in one value the major version digit. In this example, to 2015.2.0:

...e/networking-midonet (master) > cat PKG-INFO | grep Version
Version: 2015.2.0

Edit the setup.cfg file and make sure the version tag is incremented in one value too in the second digit:

...e/networking-midonet (master) > cat setup.cfg | grep version
version = 2015.2.0

Edit the file requirements.txt and make sure there are references to the master branches of neutron and neutron-lbaas project. In this case `master

  ...e/networking-midonet (master) > cat requirements.txt | grep neutron
-e git://git.openstack.org/openstack/neutron.git@master#egg=neutron
-e git://git.openstack.org/openstack/neutron-lbaas.git@master#egg=neutron-lbaas
...e/networking-midonet (master) >

Edit the file devstack/settings and make sure the MidoNet branch is pinned to master:

...e/networking-midonet (release/kilo) > cat devstack/settings | grep MIDONET_BRANCH
MIDONET_BRANCH=${MIDONET_BRANCH:-master}

Push your changes:

  $ git review

Release candidate of bugfix version

(TODO)

New bugfix version

(TODO)

Requirements.txt

It is important to manage correctly the requirements.txt file which handles the dependencies of the project.

Besides other dependencies, networking-midonet depends on development versions of neutron and neutron-lbaas. Ex:

-e git://git.openstack.org/openstack/neutron.git@master#egg=neutron
-e git://git.openstack.org/openstack/neutron-lbaas.git@master#egg=neutron-lbaas

The text between the @ and the # defines the branch we depend on.

Generally:

  • networking-midonet master branch will depend on master branch of both projects
  • networking-midonet stable/xxx branch will depend on stable/xxx branch of both projects
  • networking-midonet release/xxx branch will depend on last tag released of both projects

There is an exception: if these projects have been released with a new version but networking-midonet is not yet ready. In this case.

  • networking-midonet master branch will depend on the last tag released on both projects
  • stable/xxx and release/xxx should not exist.

What to do on a new bugfixing version of Neutron

When Neutron releases a new bugfix version, we have to dump all the changes from stable/xxx branch into release/xxx branch, update the tags to the new version, and release a new version of the plugin with these bugfixes as soon as posible.

Let's say Neutron last version is 2015.1.3 and networking-midonet last version is 2015.1.5 (generally it will be higher: neutron's bugfix + plugin bugfix releases). Now, Neutron releases a new 2015.1.4 bugfix version. Steps to follow:

  1. Rebase stable/xxx to release/xxx 
 $ git fetch
 $ git checkout stable/kilo
 $ git rebase release/kilo

You may need to resolve a conflict now...

Squash all the patches into a single one in release/kilo (we don't want to create several patches to push into gerrit)

 $ git chechout release/kilo
 $ git merge stable/kilo # No conflicts here
 $ git rebase -i HEAD~N  # Where N is the number of commits rebased from stable branch

And, once all the commits from stable/xxx are squashed in a single one, push the release/xxx branch to gerrit:

 $ git review release/kilo
  1. Release a new branch?

Consider if it is needed to release a new branch (Generally yes). If so, follow the steps on Release candidate of bugfix version

Add a custom footer
Clone this wiki locally