Tags and branches
- Each release is identified by a tag of the form
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
- 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)
- For a patch release, work on the appropriate
branchX.Y and cherry-pick as needed.
- Release notes live in
docs/releases/vX.Y.Z.rst, and must be linked from
- Update version numbers in both
tornado/__init__.py. See the comments in
__init__.py about the
version_info struct. Sample commit
- Tag the release:
git tag -a vX.Y.Z and paste the release notes into the editor window that pops up.
- Build the release tarball:
python setup.py sdist (The tarball goes in
- 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
- Push the tag to github:
git push origin vX.Y.Z. Also push all updated branches.
- 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.
- Upload the releases:
twine upload dist/tornado-X.Y.Z.tar.gz; twine upload downloads/tornado-X.Y.Z-*.whl
- If this release creates a new
branchX.Y, go to
readthedocs.org and enable builds for that branch.
- 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
- 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.
- Announce on python-tornado and python-tornado-announce mailing lists.