Maintainer’s Guide¶
The tzdata
repo is intended to be very low-maintenance and highly
automated. This document serves as a reference guide for various maintenance
actions that a maintainer may need to take. End users do not need to be
concerned with the contents of this document.
Requirements¶
Maintenance scripts are orchestrated using tox
environments to manage the
requirements of each script. The details of each environment can be found in
the tox.ini
file in the repository root.
The repository also has pre-commit configured to automatically enforce various
code formatting rules on commit. To use it, install pre-commit and run pre-commit install
in the repository
root to install the git commit hooks.
Updating to new tz releases¶
When the update
environment is run, it will automatically detect whether
the current version of the IANA time zone database in the repository matches
the latest release available from iana.org. If a new release is available, tox -e
update
will download and install it into the repository.
After running tox -e update
, the base version should be set to the current
version of the upstream database, translated into PEP 440. The package
version will start as a release candidate (rc0
), and will need to be bumped
to a full release before the final upload to PyPI. For example, when updating
from 2019c to 2020a:
$ tox -e update -- --version=2020a
...
$ git diff VERSION
-2019.3
+2020.1rc0
Once this is done, commit all the changed or added files and make a pull request.
Updating the version¶
The canonical location for the version is the VERSION
file in the
repository root, and it is updated in two ways:
The “base version” (e.g. 2020.1) is set by
tox -e update
.The additional markers such as pre (release candidate), post and dev are managed by
tox -e bump_version
.
The version follows the scheme:
YYYY.minor[rcX][.postY][.devZ]
Bumping any component removes all values to its right as well, so for example,
if the base version were 20201rc1.post2.dev0
:
$ tox -e bump -- --dev --dry-run
...
2020.1rc1.post2.dev0 → 2020.1rc1.post2.dev1
$ tox -e bump -- --post --dry-run
...
2020.1rc1.post2.dev0 → 2020.1rc1.post3
$ tox -e bump -- --rc --dry-run
...
2020.1rc1.post2.dev0 → 2020.1rc2
To remove all additional markers and get a simple “release” version, use
--release
:
$ tox -e bump -- --release
...
2020.1rc1.post2.dev0 → 2020.1
For more information on how to use bump_version
, run tox -e bump_version
-- -help
.
Making a release¶
Release automation is done via the publish.yml
GitHub Actions workflow,
which is triggered whenever a new tag is pushed and whenever a new GitHub
release is made. When a new tag is pushed, the project is built and released to
Test PyPI, and when a GitHub release is made, the
project is built and released to PyPI.
To make a release:
Tag the repository with the current version – you can use the
./tag_release.sh
script in the repository root to source the version automatically from the currentVERSION
file.Wait for the GitHub action to succeed, then check the results on https://test.pypi.org/project/tzdata/ .
If everything looks good, go into the GitHub repository’s “releases” tab and click “Create a new release”; type the name of the tag into the box, fill out the remainder of the form, and click “Publish”.
Check that the release action has succeeded, then check that everything looks OK on https://pypi.org/project/tzdata/ .
If there’s a problem with the release, use tox -e bump -- --post
to create
a post release, and if it’s sufficiently serious, yank the broken version.
It is recommended to start with a release candidate first, since even Test PyPI is immutable and each release burns a version number.