|
| 1 | +# Releasing Tornado |
| 2 | + |
| 3 | +Notes for maintainers. Pushing a `v*` tag runs the build workflow, which |
| 4 | +builds the sdist and wheels and uploads them to PyPI, so everything up to |
| 5 | +the tag has to be right before it is pushed. |
| 6 | + |
| 7 | +## Tags and branches |
| 8 | + |
| 9 | +- Each release has a tag of the form `vX.Y.Z` (such as `v6.5.0`). The tag |
| 10 | + always has all three numbers, although the trailing `.0` is usually left |
| 11 | + out elsewhere. Pre-releases have a suffix such as `a1`, `b1` or `rc1` |
| 12 | + (`v6.6.0b1`). |
| 13 | +- Final release tags are annotated: create them with `git tag -a` and paste |
| 14 | + in the release notes. Pre-release tags don't need to be. |
| 15 | +- `branchX.Y` tracks the latest release in each series. Pushes to it run |
| 16 | + the build workflow and the downstream testbed |
| 17 | + (`.github/workflows/downstream.yml`), which runs the test suites of the |
| 18 | + most popular dependents against the built package. These branches also |
| 19 | + host each version's documentation on readthedocs.org. |
| 20 | +- `stable` tracks the latest release (the same commit as the newest |
| 21 | + `branchX.Y`) and is the default version of the docs, so that doc URLs |
| 22 | + stay the same across versions. |
| 23 | + |
| 24 | +## Release steps |
| 25 | + |
| 26 | +1. For a patch release, work on the appropriate `branchX.Y` and |
| 27 | + cherry-pick from master as needed. |
| 28 | +2. Write the release notes in `docs/releases/vX.Y.Z.rst` and link them |
| 29 | + from `docs/releases.rst`. |
| 30 | +3. Update `version` and `version_info` in `tornado/__init__.py` (the |
| 31 | + comments there explain `version_info`). |
| 32 | +4. Run `python maint/scripts/pre_tag_checks.py vX.Y.Z` on the commit to be |
| 33 | + tagged. It checks the version number and release notes against the tag, |
| 34 | + runs the full test suite, lint, docs and coverage, and compares |
| 35 | + benchmarks with the previous release. |
| 36 | +5. Tag the release (`git tag -a vX.Y.Z` for a final release, pasting in the |
| 37 | + release notes), then push the tag (`git push origin vX.Y.Z`) and all |
| 38 | + updated branches, including `stable` for a final release. CI builds the |
| 39 | + sdist and wheels and uploads them to PyPI. |
| 40 | +6. If the release creates a new `branchX.Y`, enable builds for that branch |
| 41 | + on readthedocs.org. |
| 42 | +7. On master, set the version to the next development version: between |
| 43 | + releases it has a `.dev1` suffix (`6.6.0` is followed by `6.7.dev1`), or |
| 44 | + occasionally `.dev2` and so on to mark milestones. |
| 45 | +8. Announce the release on the |
| 46 | + [python-tornado](https://groups.google.com/g/python-tornado) and |
| 47 | + [python-tornado-announce](https://groups.google.com/g/python-tornado-announce) |
| 48 | + mailing lists, and in a GitHub release. |
| 49 | + |
| 50 | +## Minor releases (X.Y.0) |
| 51 | + |
| 52 | +Ship at least one pre-release (`vX.Y.0b1`, optionally an alpha first and a |
| 53 | +release candidate after) and announce it the same way. Leave about two |
| 54 | +weeks between the first beta and the final release, so downstream projects |
| 55 | +and users have time to report problems. |
| 56 | + |
| 57 | +### Deprecations |
| 58 | + |
| 59 | +A public name, argument or behavior is removed only after at least one |
| 60 | +minor release in which it emits a `DeprecationWarning` and is documented |
| 61 | +with a `.. deprecated::` note saying what to use instead. The API snapshot |
| 62 | +test (`tornado/test/api_test.py`) makes any removal show up in review. |
| 63 | + |
| 64 | +## Patch releases (X.Y.Z) |
| 65 | + |
| 66 | +Patch releases have no beta, so the pre-tag checks are the main |
| 67 | +protection against regressions. |
| 68 | + |
| 69 | +## Security releases |
| 70 | + |
| 71 | +Security releases skip the public pre-release, and that is where recent |
| 72 | +regressions have come from (6.5.3 was followed by 6.5.4, and 6.5.9 by |
| 73 | +6.5.10). GitHub Actions doesn't run in a security advisory's private fork, |
| 74 | +so the fix is developed and tested locally, and the public PR, CI run, |
| 75 | +build and release happen as fast as possible once the fix is disclosed. |
| 76 | +The aim is for that public CI run to be a formality, not the first real |
| 77 | +test: |
| 78 | + |
| 79 | +- Before anything is public, prepare the whole release on the fix branch: |
| 80 | + the version bump, the release notes, and a branch for each release line |
| 81 | + that gets the fix. |
| 82 | +- Run `pre_tag_checks.py` on each of those branches. It covers the full |
| 83 | + suite with the optional dependencies (including the property tests and |
| 84 | + the regression tests from earlier security fixes), lint, docs, coverage |
| 85 | + and benchmarks. What it can't cover is Windows, macOS and the wheel |
| 86 | + builds, which first run in public CI. |
| 87 | +- Keep each fix to the smallest behavior change that closes the hole. When |
| 88 | + a fix tightens behavior that applications may rely on, ship a way to opt |
| 89 | + out in the same release. Behavior changes are what downstream projects |
| 90 | + (tornado-testbed) catch, and for a security release they only see them |
| 91 | + after the release. |
| 92 | +- Be ready to make a follow-up release within a day, and say so in the |
| 93 | + advisory. |
0 commit comments