Guard release version info against typos and desync (#473)

Release 27.7.1 escaped with a year-typo'd changelog header while
__version__ still said 26.6.1: CI only checked that the changelog head
was >= __version__, and the release job's update_version() silently
patched the workspace copy before tagging and uploading (#469).

- New always-on check: the newest changelog version may never be dated
  in the future, and its month must be a valid calendar month.
- In --ensure-tag (release) mode, require the changelog head,
  __version__, and the usage.rst pre-commit rev to be exactly equal,
  and no longer run update_version() there - a mismatch now fails the
  release instead of being patched on the fly. Pre-commit keeps the
  auto-fix behavior.
- Before creating a new tag for a x.y.1 release, require its year.month
  to be the current (or immediately previous) month; patch releases of
  an existing series are exempt. Tag existence is now checked via
  ls-remote, since a shallow CI checkout has no local tags.
- Rename the 27.7.1 changelog entry to the intended 26.7.1 and sync
  __version__ and the usage.rst example accordingly.


Claude-Session: https://claude.ai/code/session_01Cqsspf84UPK1Gg5rka8hRz

Co-authored-by: Claude <noreply@anthropic.com>

Author: Zac-HD

docs/changelog.rst

@@ -4,7 +4,7 @@ Changelog
 
 `CalVer, YY.month.patch <https://calver.org/>`_
 
-27.7.1
+26.7.1
 ======
 - Add :ref:`ASYNC401 <async401>` pytest-raises-exception-group, recommending ``pytest.RaisesGroup`` over ``pytest.raises(ExceptionGroup)``. `(issue #430) <https://github.com/python-trio/flake8-async/issues/430>`_
 

docs/usage.rst

@@ -33,7 +33,7 @@ adding the following to your ``.pre-commit-config.yaml``:
    minimum_pre_commit_version: '2.9.0'
    repos:
    - repo: https://github.com/python-trio/flake8-async
-     rev: 26.6.1
+     rev: 26.7.1
      hooks:
        - id: flake8-async
          # args: ["--enable=ASYNC100,ASYNC112", "--disable=", "--autofix=ASYNC"]

flake8_async/__init__.py

@@ -38,7 +38,7 @@
 
 
 # CalVer: YY.month.patch, e.g. first release of July 2022 == "22.7.1"
-__version__ = "26.6.1"
+__version__ = "26.7.1"
 
 
 # taken from https://github.com/Zac-HD/shed

tests/check_changelog_and_version.py

@@ -3,6 +3,7 @@
 
 from __future__ import annotations
 
+import datetime
 import re
 import sys
 from pathlib import Path
@@ -24,6 +25,10 @@
 T = TypeVar("T", bound="Version")
 
 
+def today() -> datetime.date:
+    return datetime.datetime.now(tz=datetime.timezone.utc).date()
+
+
 class Version(NamedTuple):
     year: int
     month: int
@@ -77,6 +82,19 @@ def test_last_release_against_changelog() -> None:
     assert latest_release >= VERSION, f"{latest_release}, {VERSION}"
 
 
+def test_latest_release_is_not_in_the_future() -> None:
+    # With CalVer, a typo'd year or month gives a version that quietly sorts
+    # after every correct release (https://github.com/python-trio/flake8-async/issues/469),
+    # so the newest changelog entry may never be dated later than today.
+    latest = next(iter(get_releases()))
+    now = today()
+    assert 1 <= latest.month <= 12, f"{latest} does not have a valid month"
+    assert (latest.year + 2000, latest.month) <= (
+        now.year,
+        now.month,
+    ), f"latest release {latest} is dated in the future (today is {now:%Y-%m})"
+
+
 def test_version_increments_are_correct() -> None:
     versions = list(get_releases())
     for prev, current in zip(versions[1:], versions):
@@ -90,15 +108,48 @@ def test_version_increments_are_correct() -> None:
             assert current == prev._replace(patch=prev.patch + 1), msg
 
 
+def check_version_info_is_in_sync() -> None:
+    """Assert that all places stating a version agree, before release.
+
+    In pre-commit, update_version() auto-fixes these instead; but at release
+    time nothing may be patched up on the fly, or the built package would not
+    match the repository contents.
+    """
+    latest = next(iter(get_releases()))
+    assert (
+        latest == VERSION
+    ), f"changelog head is {latest}, but __version__ is {VERSION}"
+    m = re.search(r"^     rev: (\d+\.\d+\.\d+)$", USAGE.read_text(), flags=re.MULTILINE)
+    assert m is not None, "pre-commit example not found in usage.rst"
+    assert m.group(1) == str(VERSION), (
+        f"pre-commit example in usage.rst pins rev {m.group(1)}, "
+        f"but __version__ is {VERSION}"
+    )
+
+
 def ensure_tagged() -> None:
     last_version = next(iter(get_releases()))
     repo = Repo(ROOT_PATH)
-    if str(last_version) not in iter(map(str, repo.tags)):
-        # create_tag is partially unknown in pyright, which kinda looks like
-        # https://github.com/gitpython-developers/GitPython/issues/1473
-        # which should be resolved?
-        repo.create_tag(str(last_version))  # type: ignore
-        repo.remotes.origin.push(str(last_version))
+    # Local tags can be missing in a shallow CI checkout, so ask the remote.
+    if repo.git.ls_remote("origin", f"refs/tags/{last_version}"):
+        return
+    if last_version.patch == 1:
+        # A new year.month series must match the date it is released (patch
+        # releases keep the year.month of their series, so aren't checked).
+        # One month of slack covers a release PR merged just after month end.
+        now = today()
+        months_ago = (now.year - 2000 - last_version.year) * 12 + (
+            now.month - last_version.month
+        )
+        assert 0 <= months_ago <= 1, (
+            f"refusing to tag {last_version}: today is {now:%Y-%m}, and with"
+            " CalVer the version should match the date of release"
+        )
+    # create_tag is partially unknown in pyright, which kinda looks like
+    # https://github.com/gitpython-developers/GitPython/issues/1473
+    # which should be resolved?
+    repo.create_tag(str(last_version))  # type: ignore
+    repo.remotes.origin.push(str(last_version))
 
 
 def update_version() -> None:
@@ -128,7 +179,10 @@ def update_version() -> None:
 if __name__ == "__main__":
     test_last_release_against_changelog()
     test_version_increments_are_correct()
+    test_latest_release_is_not_in_the_future()
 
-    update_version()
     if "--ensure-tag" in sys.argv:
+        check_version_info_is_in_sync()
         ensure_tagged()
+    else:
+        update_version()