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:

  1. The “base version” (e.g. 2020.1) is set by tox -e update.

  2. 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:

  1. 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 current VERSION file.

  2. Wait for the GitHub action to succeed, then check the results on https://test.pypi.org/project/tzdata/ .

  3. 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”.

  4. 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.