Release Procedure

Outline

• We will strive to maintain backwards compatibility for the entire life of the Major release.
• In cases where backwards compatibility will be broken, we will provide deprecation warnings one minor release in advance.
• Each Major.Minor release gets a tag.
• If we need to make bug fixes on a previous release, we'll start a Major.Minor branch, cherry-pick commits from master and tag a Major.Minor.Revision release.

Prereqs

Assuming the project is already [registered with PyPi] (http://guide.python-distribute.org/contributing.html#registering-projects) and your .pypirc is in your home dir, you can upload the source distribution to the world

Procedure

1. Run tests, make code changes, check docs, dot your i's, cross your t's, remove egregious curse words and slanderous insults and generally make everything super spiffy.

# Tests MUST pass
coverage run utils/run_tests.py

2. Edit madrona/version.py if you're moving to a final release (if not keep the dev release number); change the VERSION variable to the next minor version release by removing the "dev"

# OLD VERSION was 4.0.dev
# VERSION = (4, 0, 0, 'alpha', 0)
# VERSION = (MAJOR, MINOR, REVISION, alpha|beta|rc|final, NUM)

# NEW VERSION is 4.0 according to madrona.get_version()
VERSION = (4, 0, 0, 'final', 0)

3. Run the source distribution and inspect the contents

python setup.py sdist
python setup.py check
cd dist
tar -xzvf madrona-4.0.tar.gz
cd madrona-4.0 # inspect

4. When things are looking good, pull the trigger.

vim CHANGELOG.txt # make sure everything is accounted for
git add madrona/version.py CHANGELOG.txt
git commit -a -m "bumping version"
python utils/deploy.py  # this will tag, build and publish

5. Now push the commits and tags to github

git push --tags

6. Make the docs (see Making madrona docs)

7. Now increment the version and check in the new development master

# in madrona/version.py
VERSION = (4, 1, 0, 'alpha', 0)
# NEW RELEASE will be `4.1dev` according to madrona.get_version()

git add madrona/version.py
git commit -m "Bump version"

8. If we need to make a revision on a previous release, go back and branch off the tag, do some work and tag/release a new revision.

git checkout master
# Make changes and commit them; note the rev hash
git checkout -b v4.0.0 v4.0
git cherry-pick 5d3e1b6 #### ALWAYS cherry-pick a change that was also applied to master
git commit -a -m "Cherry picking the bugfix"
# in version.py
VERSION = (4, 0, 1, 'final', 0)
git commit -a -m "release 4.0.1"
python deploy.py
git push --tags v4.0.1 origin/v4.0.1