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.
Maintenance scripts are orchestrated using
tox environments to manage the
requirements of each script. The details of each environment can be found in
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¶
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,
update will download and install it into the repository.
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
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:
Bumping any component removes all values to its right as well, so for example,
if the base version were
$ 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
$ tox -e bump -- --release
2020.1rc1.post2.dev0 → 2020.1
For more information on how to use
tox -e bump_version
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.shscript in the repository root to source the version automatically from the current
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.