.. index:: ! releasing Release - how to ================ .. contents:: How to release .. index:: git; git flow This is a checklist for releasing a new version of *something* if we're using the Git Flow process for development. Git branches ------------ Since we use Git Flow, the two branches of concern at release time are: * **master** - always has the most recently released code. Each release is tagged `X.X.X`. * **develop** - contains the code under development for the next release So technically, what makes a new release is merging `develop` to `master` and tagging it. Of course, we don't want to do that until we're ready. We also use the git flow tool to help with the Git Flow branching model, especially for releases. Release steps ------------- Take these steps to release the new version: * Make a fresh clone of the repo (to make sure we're working off the same code that's on github): git clone git@github.com:org/project.git cd project * Set up git flow in this new repo:: git checkout master git flow init -d * Start release branch using git flow: git flow release start e.g. git flow release start '0.0.5' Do **not** include ``v`` on the front of the version number - there's nothing wrong with it, we're just not using it for our version numbers here and want to be consistent. * Run the tests locally. The tests must pass before proceeding. Fix any problems and commit the changes. * Set `VERSION` in `project/__init__.py` to the same version, e.g. `VERSION = '0.0.5'`. * Start a new section in `RELEASE_NOTES.rst` for the new release. Always put the new release section above the previous ones. * Review `git log` and add major new features and incompatibilities to the release notes. * Commit changes. Be sure to include the new version number in the commit message first line, e.g. "Bump version for 0.0.5". * Push the release branch. * Open a pull request from the release branch to the master branch. * When pull request has been reviewed, use **git flow commands** to make the release: git flow release finish '0.0.5' You'll be prompted for a commit message for the merge to master. The default is fine (`Merge branch 'release/0.0.5'`). You'll be prompted for a tag message. Make it "Tag for v0.0.5" or whatever the version is. You'll be prompted for a commit message for the merge back to develop. The default is fine. * Push the merged master and develop branch and tag to github: git push origin master --tags git push origin develop --tags * Verify that CI tests have passed for the pushed master * Email the release announcement