Merge pull request #20 from python/version_file

Change version bumping scheme

Author: pganssle

.pre-commit-config.yaml

@@ -16,7 +16,6 @@ repos:
     rev: v2.4.0
     hooks:
       - id: trailing-whitespace
-      - id: end-of-file-fixer
       - id: debug-statements
 
   - repo: https://github.com/asottile/setup-cfg-fmt

MANIFEST.in

@@ -1 +1,2 @@
 recursive-include src/tzdata *
+include VERSION

VERSION

@@ -0,0 +1 @@
+2020.1rc0

bump_version.py

@@ -0,0 +1,111 @@
+import argparse
+import io
+import pathlib
+
+import parver
+
+REPO_ROOT = pathlib.Path(__file__).parent
+VERSION = REPO_ROOT / pathlib.Path("VERSION")
+
+
+def get_current_version() -> parver.Version:
+    with open(VERSION, "rt") as f:
+        return parver.Version.parse(f.read().strip())
+
+
+def write_version(version: parver.Version):
+    with open(VERSION, "wt") as f:
+        f.write(str(version))
+
+
+def update_package_version(version: parver.Version):
+    new_init = io.StringIO()
+    version_set = False
+    init = REPO_ROOT / "src" / "tzdata" / "__init__.py"
+    with open(init, "rt") as f:
+        for line in f:
+            if not version_set and line.startswith("__version__"):
+                line = f'__version__ = "{version}"\n'
+                version_set = True
+            new_init.write(line)
+
+    if not version_set:
+        raise ValueError("Version not found in __init__.py!")
+
+    new_init.seek(0)
+
+    with open(init, "wt") as f:
+        f.write(new_init.read())
+
+
+def bump_version(version: parver.Version, args) -> parver.Version:
+    if args.release:
+        return version.base_version()
+
+    if args.dev:
+        if args.to is not None:
+            return version.replace(dev=args.to)
+        else:
+            return version.bump_dev()
+
+    version = version.replace(dev=None)
+
+    if args.post:
+        if args.to is not None:
+            return version.replace(post=args.to)
+        else:
+            return version.bump_post()
+
+    if args.rc:
+        if version.is_postrelease:
+            version = version.replace(post=None)
+
+        if args.to is not None:
+            return version.replace(pre_tag="rc", pre=args.to)
+        else:
+            return version.bump_pre("rc")
+
+
+def main(args):
+    original_version = get_current_version()
+    bumped_version = bump_version(original_version, args)
+
+    print(f"{original_version} → {bumped_version}")
+    if not args.dry_run:
+        write_version(bumped_version)
+        update_package_version(bumped_version)
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="Manipulate the package version")
+
+    group = parser.add_mutually_exclusive_group(required=True)
+
+    group.add_argument("--rc", action="store_true", help="Bump the release candidate")
+    group.add_argument("--dev", action="store_true", help="Bump the dev version")
+    group.add_argument(
+        "--release",
+        action="store_true",
+        help="Bump from release candidate / dev to release",
+    )
+    group.add_argument(
+        "--post", action="store_true", help="Bump the post release version"
+    )
+    parser.add_argument(
+        "--to",
+        type=int,
+        default=None,
+        help="Set the specified component to a specific number",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Preview what the new version will be without writing any files.",
+    )
+
+    args = parser.parse_args()
+
+    if args.to is not None and args.release:
+        raise ValueError("Cannot combine --to and --release")
+
+    main(args)

docs/index.rst

@@ -117,9 +117,10 @@ to package names:
 .. _zoneinfo: https://docs.python.org/3/library/zoneinfo.html
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
    :caption: Contents:
 
+   maintaining
 
 
 Indices and tables

docs/maintaining.rst

@@ -0,0 +1,115 @@
+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
+<https://pre-commit.com/>`_ 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
+<https://www.iana.org/time-zones>`_. 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 <https://test.pypi.org>`_, and when a GitHub release is made, the
+project is built and released to `PyPI <https://pypi.org>`_.
+
+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
+   <https://github.com/python/tzdata/releases>`_ 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.
+
+.. Links
+.. |tox| replace:: ``tox``
+.. _tox: https://tox.readthedocs.io/en/latest/

setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = tzdata
-version = attr:tzdata.__version__
+version = file: VERSION
 description = Provider of IANA time zone data
 long_description = file: README.rst
 long_description_content_type = text/x-rst

src/tzdata/__init__.py

@@ -1,6 +1,6 @@
 # IANA versions like 2020a are not valid PEP 440 identifiers; the recommended
-# way to translate the version is to use YYYY.n where `n` is a 1-based index.
-__version__ = "2020.1"
+# way to translate the version is to use YYYY.n where `n` is a 0-based index.
+__version__ = "2020.1rc0"
 
 # This exposes the original IANA version number.
 IANA_VERSION = "2020a"

tag_release.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/bash
+set -e
+VERSION=$(<VERSION)
+
+echo "Tagging version $VERSION"
+git tag -s -m "Version $VERSION" $VERSION || exit "Failed to tag!"
+echo "Succeess"

tox.ini

@@ -18,17 +18,29 @@ skip_install = True
 deps =
     requests
     click
+    parver
 commands =
     python update.py {posargs}
 
+[testenv:bump]
+description = Bump the current package version
+skip_install = True
+deps =
+    parver
+commands =
+    python bump_version.py {posargs}
+
+
 [testenv:pytype]
 description = Run typechecking
 basepython = python3.7
 skip_install = True
 deps =
     pytype
+    parver
 commands =
     pytype {posargs} update.py
+    pytype {posargs} bump_version.py
 
 [testenv:format]
 description = Run auto formatters

update.py

@@ -10,7 +10,7 @@
 import typing
 
 import click
-
+import parver
 import requests
 
 IANA_LATEST_LOCATION = "https://www.iana.org/time-zones/repository/tzdata-latest.tar.gz"
@@ -105,7 +105,10 @@ def create_package(
     version: str, zonenames: typing.List[str], zoneinfo_dir: pathlib.Path
 ):
     """Creates the tzdata package."""
-    package_version = translate_version(version)
+    # Start out at rc0
+    base_version = parver.Version.parse(translate_version(version))
+    rc_version = base_version.replace(pre_tag="rc", pre=0)
+    package_version = str(rc_version)
 
     # First remove the existing package contents
     target_dir = PKG_BASE / "tzdata"
@@ -126,6 +129,9 @@ def create_package(
         with open(target_dir / "__init__.py", "w") as f_out:
             f_out.write(contents)
 
+    with open(REPO_ROOT / "VERSION", "w") as f:
+        f.write(package_version)
+
     # Generate the "zones" file as a newline-delimited list
     with open(target_dir / "zones", "w") as f:
         f.write("\n".join(zonenames))