-
Notifications
You must be signed in to change notification settings - Fork 89
Branching Model
This page explains the branching model for the projects.
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
-
Must be branched off
- Version in source:
vX.Y.Z.<id>
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?
The versioning model of MidoNet follows semantic versioning, but this may change in the near future.
NOTE: this graph is out of date, we'll be fixing it soon. The releases and hotfixes are made in BRANCHES, not TAGs.
- Red # bugfix * Green = change to version number committed in repo * Yellow = feature freeze point * Red-on-yellow = hotfi * Bold = branch * Italics tag
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.
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.
Tags are created for every release of the plugin always in the 'releases/xxx' branch!
Please refer to Packaging#neutron-midonet-plugin to find the version number format.
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
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:
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.
Major release version is the one that give us more work to do. We have to:
- Create the tag
- [[Create the
release/xxx
branch|Branching-Model#create-the-releasexxx-branch]] - [[Create the
stable/xxx
branch|Branching-Model#create-the-stablexxx-branch]] - Update the master branch to new release
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.
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
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
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
(TODO)
(TODO)
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 onmaster
branch of both projects -
networking-midonet
stable/xxx
branch will depend onstable/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
andrelease/xxx
should not exist.
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:
- Rebase
stable/xxx
torelease/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
- 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