improve changelog/release handling (#321)

* move changelog&version check to pre-commit and separate CI job that is not required for merging

* add --allow-future

* allow later release number in changelog

Author: jakkdl

.github/workflows/ci.yml

@@ -30,7 +30,7 @@ jobs:
         runs-on: ubuntu-latest
         strategy:
             matrix:
-                python-version: ['3.9', '3.10', '3.11', '3.12', 3.13]
+                python-version: ['3.9', '3.10', '3.11', '3.12', '3.13']
             fail-fast: false
         steps:
             - uses: actions/checkout@v4
@@ -62,10 +62,21 @@ jobs:
             - name: Run tests
               run: python -m tox -e flake8_7 -- --onlyfuzz --no-cov -n auto
 
+    check_release:
+        runs-on: ubuntu-latest
+        strategy:
+            fail-fast: false
+        steps:
+            - uses: actions/checkout@v4
+            - name: Set up Python 3
+              uses: actions/setup-python@v5
+            - name: Test changelog & version
+              run: python tests/check_changelog_and_version.py
+
     release:
         runs-on: ubuntu-latest
-        needs: [pyright, test]
-        if: github.repository == 'python-trio/flake8-async' &&  github.ref == 'refs/heads/main'
+        needs: [pyright, test, check_release]
+        if: github.repository == 'python-trio/flake8-async' && github.ref == 'refs/heads/main'
         steps:
             - uses: actions/checkout@v4
             - name: Set up Python 3
@@ -77,5 +88,4 @@ jobs:
                   TWINE_USERNAME: __token__
                   TWINE_PASSWORD: ${{ secrets.TWINE_PASSWORD }}
               run: |
-                  python tests/test_changelog_and_version.py --ensure-tag
                   python -m build && twine upload --skip-existing dist/*

.pre-commit-config.yaml

@@ -3,8 +3,9 @@ default_language_version:
     python: python3.12
 # pyright requires internet connection to run, which the pre-commit ci app doesn't have.
 # it instead runs in a github action
+# check-release-changelog is run as a dedicated job
 ci:
-    skip: [pyright]
+    skip: [pyright, check-release-changelog]
 
 repos:
     - repo: https://github.com/astral-sh/ruff-pre-commit
@@ -100,3 +101,16 @@ repos:
       rev: v1.0.0
       hooks:
           - id: sphinx-lint
+
+    - repo: local
+      hooks:
+          - id: check-release-changelog
+            name: check-release-changelog
+            language: system
+            entry: python3 tests/check_changelog_and_version.py --allow-future-in-changelog
+            files: flake8_async/__init__.py|docs/changelog.rst
+
+    - repo: meta
+      hooks:
+          - id: check-hooks-apply
+          - id: check-useless-excludes

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: 23.2.5
+     rev: 24.11.4
      hooks:
        - id: flake8-async
          # args: [--enable=ASYNC, --disable=ASYNC9, --autofix=ASYNC]

tests/test_changelog_and_version.py tests/check_changelog_and_version.py

@@ -13,9 +13,11 @@
 
 ROOT_PATH = Path(__file__).parent.parent
 CHANGELOG = ROOT_PATH / "docs" / "changelog.rst"
-README = ROOT_PATH / "README.md"
+USAGE = ROOT_PATH / "docs" / "usage.rst"
 INIT_FILE = ROOT_PATH / "flake8_async" / "__init__.py"
 
+ALLOW_FUTURE = "--allow-future-in-changelog" in sys.argv
+
 T = TypeVar("T", bound="Version")
 
 
@@ -44,6 +46,7 @@ def get_releases() -> Iterable[Version]:
     valid_pattern = re.compile(r"^(\d\d\.\d?\d\.\d?\d)$")
     header_pattern = re.compile(r"^=+$")
     last_line_was_date = False
+    last_line: str | None = None
     with open(CHANGELOG, encoding="utf-8") as f:
         lines = f.readlines()
     for line in lines:
@@ -54,15 +57,21 @@ def get_releases() -> Iterable[Version]:
         elif version_match:
             yield Version.from_string(version_match.group(1))
             last_line_was_date = True
-        else:
-            # stop lines such as `Future\n=====` making it through to main/
-            assert not header_pattern.match(line), line
+        # only allow `Future\n=====` when run in pre-commit
+        elif header_pattern.match(line):
+            assert ALLOW_FUTURE, "FUTURE header with no --allow-future-in-changelog. "
+            assert last_line is not None
+            assert last_line.lower().strip() == "future"
+        last_line = line
 
 
 def test_last_release_against_changelog() -> None:
-    """Ensure we have the latest version covered in 'changelog.rst'."""
+    """Ensure we have the latest version covered in 'changelog.rst'.
+
+    If changelog version is greater, the __init__ gets bumped in update_version().
+    """
     latest_release = next(iter(get_releases()))
-    assert latest_release == VERSION
+    assert latest_release >= VERSION, f"{latest_release}, {VERSION}"
 
 
 def test_version_increments_are_correct() -> None:
@@ -98,20 +107,27 @@ def update_version() -> None:
         INIT_FILE = ROOT_PATH / "flake8_async" / "__init__.py"
         subs = (f'__version__ = "{VERSION}"', f'__version__ = "{last_version}"')
         INIT_FILE.write_text(INIT_FILE.read_text().replace(*subs))
+        print("updated VERSION in __init__.py")
 
     # Similarly, update the pre-commit config example in the README
-    current = README.read_text()
+    current = USAGE.read_text()
     wanted = re.sub(
-        pattern=r"^  rev: (\d+\.\d+\.\d+)$",
-        repl=f"  rev: {last_version}",
+        pattern=r"^     rev: (\d+\.\d+\.\d+)$",
+        repl=f"     rev: {last_version}",
         string=current,
         flags=re.MULTILINE,
     )
+    if last_version != VERSION:
+        assert current != wanted, "version changed but regex didn't substitute"
     if current != wanted:
-        README.write_text(wanted)
+        USAGE.write_text(wanted)
+        print("updated rev in pre-commit example")
 
 
 if __name__ == "__main__":
+    test_last_release_against_changelog()
+    test_version_increments_are_correct()
+
     update_version()
     if "--ensure-tag" in sys.argv:
         ensure_tagged()