Release instructions

Tags and branches

• Each release is identified by a tag of the form vX.Y.Z (e.g. v4.4.0). All three numbers are included in the tag, although the trailing .0 is generally omitted in other contexts. Beta releases have a suffix like b1.
• Release tags (non-beta) are annotated: create the tag with git tag -a v4.4.0 and paste in the release notes.
• Branches named branchX.Y track the latest release in each series. These branches are also used on readthedocs.org to host the documentation for that version.
• The branch named stable tracks the latest release (same as the most recent branchX.Y) and is used as the default version in the docs (so that URLs are stable across versions)

Release process

1. For a patch release, work on the appropriate branchX.Y and cherry-pick as needed.
2. Release notes live in docs/releases/vX.Y.Z.rst, and must be linked from docs/releases.rst.
3. Update version numbers in both setup.py and tornado/__init__.py. See the comments in __init__.py about the version_info struct. Sample commit
4. Tag the release: git tag -a vX.Y.Z and paste the release notes into the editor window that pops up.
5. Build the release tarball: python setup.py sdist (The tarball goes in dist/tornado-X.Y.tar.gz)
6. Test the release tarball in an isolated environment: virtualenv /tmp/test_env; /tmp/test_env/bin/pip install path/to/tornado-X.Y.tar.gz; /tmp/test_env/bin/python -m tornado.test
7. Push the tag to github: git push origin vX.Y.Z. Also push all updated branches.
8. This triggers a Windows binary build on appveyor.com. Download the resulting artifacts (click on the tag build, and for each of the 32- and 64-bit environments click on the artifacts tab and download the .whl file). TODO: automate this. Also consider building the source tarball and mac binaries on travis-ci.
9. Upload the releases: twine upload dist/tornado-X.Y.Z.tar.gz; twine upload downloads/tornado-X.Y.Z-*.whl
10. If this release creates a new branchX.Y, go to readthedocs.org and enable builds for that branch.
11. Update the version number on the master branch. In between releases the version number has a .dev1 suffix (or occasionally .dev2, etc, if we want to mark particular milestones in the in-development version): release 4.4.0 is followed by version 4.5.0.dev1.
12. On pypi, mark all but the latest release as "hidden". This is not automated so that beta releases don't hide the latest non-beta release.
13. Announce on python-tornado and python-tornado-announce mailing lists.