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 tornado/__init__.py. See the comments in __init__.py about the version_info struct.
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. Watch the build here, and when it's done run PYTHONPATH=. maint/scripts/download_wheels.py vX.Y.Z. TODO: 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-vX.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. Announce on python-tornado and python-tornado-announce mailing lists.