ci: Gitea checks — ruff, CPython 3.8–3.14 matrix, wheel+sdist smoke tests, ci-ok aggregate

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-05 14:20:10 -06:00
parent 13aaa221ad
commit c361b286c9
5 changed files with 226 additions and 2 deletions
@@ -0,0 +1,88 @@
+name: CI
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, edited]   # edited: un-WIP starts CI
+  push:
+    branches: [develop, main]
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  # Cancel superseded PR runs. Never cancel a push run.
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  lint:
+    if: >-
+      github.event_name != 'pull_request' || (
+        !startsWith(github.event.pull_request.title, 'WIP:') &&
+        !startsWith(github.event.pull_request.title, '[WIP]')
+      )
+    runs-on: ubuntu-latest
+    container: python:3.14
+    env:
+      UV_PYTHON_DOWNLOADS: never
+    steps:
+      - name: Install node (Gitea actions are node programs)
+        run: apt-get update && apt-get install -y --no-install-recommends nodejs
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - run: git config --global --add safe.directory "$PWD"
+      - run: pip install uv
+      - run: uv sync --locked
+      - run: uv run ruff check
+      - run: uv run ruff format --check
+
+  test:
+    if: >-
+      github.event_name != 'pull_request' || (
+        !startsWith(github.event.pull_request.title, 'WIP:') &&
+        !startsWith(github.event.pull_request.title, '[WIP]')
+      )
+    runs-on: ubuntu-latest
+    container: python:${{ matrix.python }}
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]
+    env:
+      UV_PYTHON: ${{ matrix.python }}
+      UV_PYTHON_DOWNLOADS: never
+    steps:
+      - name: Install node (Gitea actions are node programs)
+        run: apt-get update && apt-get install -y --no-install-recommends nodejs
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0     # setuptools_scm needs tags
+      - run: git config --global --add safe.directory "$PWD"
+      - run: pip install uv
+      - run: uv sync --locked
+      - run: uv run pytest
+      - name: Build, install and smoke-test the wheel and the sdist
+        run: |
+          rm -rf dist && uv build
+          for dist in dist/*.whl dist/*.tar.gz; do
+            rm -rf /tmp/smoke && uv venv /tmp/smoke
+            uv pip install --python /tmp/smoke "$dist"
+            (cd / && /tmp/smoke/bin/python "$GITHUB_WORKSPACE/scripts/smoke_import.py")
+          done
+
+  ci-ok:
+    needs: [lint, test]
+    # always(): a plain needs: aggregate would be *skipped* when a gate fails,
+    # and Gitea reports skipped as success. The WIP gate stays.
+    if: >-
+      always() && (
+        github.event_name != 'pull_request' || (
+          !startsWith(github.event.pull_request.title, 'WIP:') &&
+          !startsWith(github.event.pull_request.title, '[WIP]')
+        )
+      )
+    runs-on: ubuntu-latest
+    steps:
+      - name: Require every gate to have succeeded
+        run: |
+          echo "lint=${{ needs.lint.result }} test=${{ needs.test.result }}"
+          test "${{ needs.lint.result }}" = success
+          test "${{ needs.test.result }}" = success
@@ -30,6 +30,15 @@ uv lock                          # after any dependency change; commit uv.lock

 `requires-python` is `>=3.8`, and the claim should match what CI actually tests. When an end-of-life Python version starts failing, drop it: raise `requires-python` and remove its CI lane. Don't add compat shims, version branches or contorted code just to keep it working. Clean code matters more than supporting EOL runtimes. Users on old Pythons keep the older releases on PyPI.

+## CI
+
+`.gitea/workflows/ci.yaml` runs on PRs and on pushes to `develop`/`main`. PRs titled `WIP:` are skipped; removing the prefix starts the run.
+- `lint`: ruff.
+- `test`: a matrix over CPython 3.8–3.14 in `python:<v>` containers. Each lane runs the locked suite, then builds the wheel and sdist, installs each into a clean venv, and runs `scripts/smoke_import.py` from outside the source tree.
+- `ci-ok`: the only required check (`CI / ci-ok (pull_request)`). It uses `if: always()` and fails unless every gate succeeded, because Gitea reports a skipped job as success.
+
+`tests/test_ci_workflow.py` pins these invariants. To add or drop a Python version, change all four together: the matrix, the classifiers, `scripts/verify_index_release.sh`'s list, and `NEWEST_MINOR` (or `requires-python`).
+
 ## Architecture

 Package layout: `_bootstrap.py`, `_util.py`, `cfg.py`, `log.py`, `cli.py` and `app_container.py`. `__init__.py` re-exports the public names explicitly.
@@ -12,6 +12,8 @@ Application framework for Python, features include:
 - Colored logging (provided through colorlog)
 - Linux supported. Windows and macOS are goals, but untested.

+**Tested:** Linux, CPython 3.8–3.14 (Gitea CI on every PR). Windows and macOS: goals, untested.
+
 Principles:
 - Lend to creating beautiful, easy to read and understand code in the application.
 - Minimize coupling of applications to this framework.
@@ -20,8 +20,15 @@ authors = [
 keywords = ["cli", "logging", "application"]
 classifiers = [
    "Programming Language :: Python :: 3",
-    "License :: OSI Approved :: MIT No Attribution License (MIT-0)",
-    "Operating System :: OS Independent"
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Operating System :: POSIX :: Linux",
+    "License :: OSI Approved :: MIT No Attribution License (MIT-0)"
 ]


@@ -0,0 +1,118 @@
+"""Pins the CI workflow's invariants (spec: docs/superpowers/specs/
+2026-10-04-modernization-design.md). CI drift shows up as a red test here."""
+
+import pathlib
+import re
+
+import pytest
+import yaml
+
+ROOT = pathlib.Path(__file__).resolve().parent.parent
+WORKFLOW = ROOT / ".gitea" / "workflows" / "ci.yaml"
+VERIFY_SCRIPT = ROOT / "scripts" / "verify_index_release.sh"
+
+# Newest CPython the project claims. To add a version, bump this, the
+# matrix, the classifiers and the verify script's list together.
+NEWEST_MINOR = 14
+
+WIP_CLAUSES = (
+    "!startsWith(github.event.pull_request.title, 'WIP:')",
+    "!startsWith(github.event.pull_request.title, '[WIP]')",
+)
+
+
+def load():
+    return yaml.safe_load(WORKFLOW.read_text())
+
+
+def triggers(wf):
+    # PyYAML follows YAML 1.1, where the bare key `on` parses as boolean True.
+    return wf["on"] if "on" in wf else wf[True]
+
+
+def expected_versions():
+    text = (ROOT / "pyproject.toml").read_text()
+    floor = int(re.search(r'requires-python\s*=\s*">=3\.(\d+)"', text).group(1))
+    return ["3.%d" % minor for minor in range(floor, NEWEST_MINOR + 1)]
+
+
+def flat(text):
+    return " ".join(text.split())
+
+
+def test_triggers():
+    on = triggers(load())
+    assert set(on["pull_request"]["types"]) == {
+        "opened",
+        "synchronize",
+        "reopened",
+        "edited",
+    }
+    assert on["push"]["branches"] == ["develop", "main"]
+    assert "workflow_dispatch" in on
+
+
+def test_superseded_pr_runs_cancel_but_push_runs_never_do():
+    assert (
+        load()["concurrency"]["cancel-in-progress"]
+        == "${{ github.event_name == 'pull_request' }}"
+    )
+
+
+def test_every_job_is_wip_gated():
+    for name, job in load()["jobs"].items():
+        cond = flat(job.get("if", ""))
+        for clause in WIP_CLAUSES:
+            assert clause in cond, "%s lacks WIP gate clause %s" % (name, clause)
+
+
+def test_matrix_matches_requires_python():
+    test = load()["jobs"]["test"]
+    assert test["strategy"]["matrix"]["python"] == expected_versions()
+    assert test["strategy"]["fail-fast"] is False
+
+
+def test_classifiers_match_matrix():
+    text = (ROOT / "pyproject.toml").read_text()
+    claimed = re.findall(r'"Programming Language :: Python :: (3\.\d+)"', text)
+    assert claimed == expected_versions()
+
+
+@pytest.mark.skipif(not VERIFY_SCRIPT.exists(), reason="added with the release task")
+def test_verify_script_covers_matrix():
+    match = re.search(r"^pythons=\(([^)]*)\)", VERIFY_SCRIPT.read_text(), re.M)
+    assert match.group(1).split() == expected_versions()
+
+
+def test_checkout_fetches_full_history_for_setuptools_scm():
+    for name, job in load()["jobs"].items():
+        for step in job.get("steps", []):
+            if step.get("uses", "").startswith("actions/checkout"):
+                assert step.get("with", {}).get("fetch-depth") == 0, name
+
+
+def test_lint_job_runs_ruff():
+    runs = flat(" ".join(s.get("run", "") for s in load()["jobs"]["lint"]["steps"]))
+    assert "uv run ruff check" in runs
+    assert "uv run ruff format --check" in runs
+
+
+def test_test_lanes_run_locked_suite_and_smoke_test_both_artifacts():
+    runs = flat(" ".join(s.get("run", "") for s in load()["jobs"]["test"]["steps"]))
+    assert "uv sync --locked" in runs
+    assert "uv run pytest" in runs
+    assert "uv build" in runs
+    assert "dist/*.whl dist/*.tar.gz" in runs
+    assert "scripts/smoke_import.py" in runs
+
+
+def test_ci_ok_fails_unless_every_gate_succeeded():
+    jobs = load()["jobs"]
+    ci_ok = jobs["ci-ok"]
+    # Gitea reports a skipped job as success, so ci-ok must run always()
+    # and check each result explicitly.
+    assert set(ci_ok["needs"]) == set(jobs) - {"ci-ok"}
+    assert flat(ci_ok["if"]).startswith("always() &&")
+    runs = " ".join(s.get("run", "") for s in ci_ok["steps"])
+    for needed in ci_ok["needs"]:
+        assert 'test "${{ needs.%s.result }}" = success' % needed in runs