Test reliability, mypy, CI modernization, and automated releases

.github/workflows/checks.yml

@@ -0,0 +1,82 @@
+# Shared lint/type/test checks, callable from other workflows instead of
+# copy-pasted into them. python-package.yml calls this on every push/PR;
+# publish.yml calls it to re-verify the exact tagged commit before a release
+# goes out. Keeping the checks in one place means those two triggers can't
+# quietly drift out of sync with each other.
+
+name: checks
+
+on:
+  workflow_call:
+
+jobs:
+  lint:
+    # Static checks (Ruff, mypy) don't depend on which Python interpreter runs
+    # them, only on the tool versions and the target-version/python_version
+    # pinned in pyproject.toml. Run them once here instead of once per entry
+    # in the test matrix below.
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          submodules: true
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.14"
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Lint with Ruff
+        run: uv run ruff check --output-format=github .
+
+      - name: Format check with Ruff
+        run: uv run ruff format --check .
+
+      - name: Type check with mypy
+        run: uv run mypy overreact tests
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # Only the extremes of what pyproject.toml's requires-python
+        # actually supports (oldest) and the newest CPython release
+        # (newest) -- not every version in between. CPython's compatibility
+        # story is strongly monotonic for pure-Python code, so this catches
+        # nearly everything a full N-version matrix would while cutting CI
+        # time; the main residual risk is a version-specific bug in a
+        # compiled dependency (this project leans on NumPy/SciPy/JAX) on an
+        # untested intermediate version, which is judged an acceptable
+        # tradeoff here. Bump both ends as Python's own support windows move
+        # (https://endoflife.date/python) and pyproject.toml's requires-python
+        # changes.
+        python-version: ["3.12", "3.14"]
+
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          submodules: true
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        # --all-extras is required (not just recommended): it installs jax/jaxlib
+        # (the "fast" extra), which several doctests in overreact/simulate.py
+        # depend on for their expected output. See CONTRIBUTING.md.
+        run: uv sync --all-extras
+
+      - name: Test with pytest
+        run: uv run pytest --cov=. --cov-report=xml
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v7
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}

.github/workflows/codeql-analysis.yml

@@ -14,12 +14,18 @@ name: "CodeQL"
 on:
   push:
     branches: [main]
+    paths-ignore: ["**.md"]
   pull_request:
     # The branches below must be a subset of the branches above
     branches: [main]
+    paths-ignore: ["**.md"]
   schedule:
     - cron: "44 22 * * 4"
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   analyze:
     name: Analyze
@@ -45,26 +51,15 @@ jobs:
         uses: github/codeql-action/init@v4.37.8
         with:
           languages: ${{ matrix.language }}
+          # Python is interpreted, not compiled: there's nothing for Autobuild
+          # to build, so skip straight to source extraction instead of running
+          # (and paying for) a no-op build step. Revisit this if a compiled
+          # language is ever added to the matrix above.
+          build-mode: none
           # If you wish to specify custom queries, you can do so here or in a config file.
           # By default, queries listed here will override any specified in a config file.
           # Prefix the list here with "+" to use these queries and those in the config file.
           # queries: ./path/to/local/query, your-org/your-repo/queries@main
 
-      # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
-      # If this step fails, then you should remove it and run the build manually (see below)
-      - name: Autobuild
-        uses: github/codeql-action/autobuild@v4.37.8
-
-      # ℹ️ Command-line programs to run using the OS shell.
-      # 📚 https://git.io/JvXDl
-
-      # ✏️ If the Autobuild fails above, remove it and uncomment the following three lines
-      #    and modify them (or add more) to build your code if your project
-      #    uses a compiled language
-
-      #- run: |
-      #   make bootstrap
-      #   make release
-
       - name: Perform CodeQL Analysis
         uses: github/codeql-action/analyze@v4.37.8

.github/workflows/docs.yml

@@ -0,0 +1,74 @@
+# Builds API docs with pdoc (see gendocs.sh) and deploys them to GitHub
+# Pages via Actions -- replacing the previous setup, where a maintainer ran
+# gendocs.sh locally and committed the generated docs/ folder to main.
+#
+# Requires Pages source to be set to "GitHub Actions" in Settings -> Pages
+# -> Build and deployment -> Source (a repo admin, on GitHub; not something
+# this workflow can do for itself). Already done for this repo -- if it's
+# ever reset to "Deploy from a branch", this workflow will keep building
+# docs successfully but the deploy step will fail (Pages stops listening
+# for Actions deployments).
+
+name: Deploy docs to Pages
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "overreact/**"
+      - "README.md"
+      - "gendocs.sh"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Pages deployments shouldn't race each other or be cancelled mid-flight by
+# a newer push (unlike checks.yml/CI, where cancelling a superseded run is
+# fine) -- queue them instead.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      # No `submodules: true` here, unlike the other workflows: pdoc only
+      # introspects docstrings/signatures, it never touches data/, and
+      # overreact/_datasets.py's module-level directory walk degrades to an
+      # empty dict (not an error) when data/ is absent.
+      - uses: actions/checkout@v7
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.14"
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Build docs
+        run: uv run bash gendocs.sh -o docs-build
+
+      - name: Configure Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload docs artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs-build
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/publish.yml

@@ -0,0 +1,137 @@
+# Publishes overreact to PyPI whenever a version tag (e.g. v1.2.0) is pushed.
+#
+# Uses PyPI's Trusted Publishing (OIDC): no PyPI API token is stored as a
+# repository secret. This requires a one-time setup on PyPI by a project
+# owner, done *before* the first tag is pushed after adding this workflow:
+# https://docs.pypi.org/trusted-publishers/adding-a-publisher/
+#   - Publisher: GitHub
+#   - Owner: geem-lab
+#   - Repository: overreact
+#   - Workflow name: publish.yml
+#   - Environment name: pypi
+#
+# The `pypi` environment referenced below also lets you require manual
+# approval before a publish goes out -- Settings -> Environments -> pypi ->
+# "Required reviewers" -- without touching this file.
+
+name: Publish
+
+on:
+  push:
+    tags: ["v*.*.*"]
+
+permissions:
+  contents: read
+
+jobs:
+  checks:
+    # Guard against a fork pushing a matching tag and trying to build/publish
+    # under this identity (trusted publishing would reject it anyway, since
+    # it's bound to this exact repository + workflow, but fail fast and
+    # quietly instead of burning CI time on a run that can't succeed).
+    if: github.repository == 'geem-lab/overreact'
+    # Re-run the exact same lint/type/test checks as python-package.yml
+    # (checks.yml), against the exact tagged commit: a tag can in principle
+    # point anywhere, so a release shouldn't only trust that *some* commit on
+    # main once passed CI. Sharing the workflow file instead of duplicating
+    # its steps here means the two can't drift out of sync.
+    uses: ./.github/workflows/checks.yml
+    secrets: inherit
+
+  build:
+    needs: checks
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.check-version.outputs.version }}
+
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          submodules: true
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.14"
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Verify tag matches package version
+        # Catches the classic footgun of tagging a commit whose
+        # pyproject.toml version wasn't actually bumped to match, before
+        # a single-use, non-reusable PyPI version gets burned on it.
+        id: check-version
+        run: |
+          tag_version="${GITHUB_REF_NAME#v}"
+          pkg_version="$(uv run python -c 'import overreact; print(overreact.__version__)')"
+          if [ "$tag_version" != "$pkg_version" ]; then
+            echo "::error::tag $GITHUB_REF_NAME does not match package version $pkg_version (pyproject.toml)"
+            exit 1
+          fi
+          echo "version=$pkg_version" >> "$GITHUB_OUTPUT"
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      # needs.build.outputs.version is the tag with its leading "v" already
+      # stripped (e.g. "1.2.0"), matching PyPI's actual URL scheme -- unlike
+      # github.ref_name (e.g. "v1.2.0"), which PyPI has no page for.
+      url: https://pypi.org/project/overreact/${{ needs.build.outputs.version }}
+    permissions:
+      id-token: write # required for PyPI Trusted Publishing (OIDC)
+
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        # No username/password/token: identity comes from OIDC + the `pypi`
+        # environment above. Sigstore build provenance attestations are
+        # generated and uploaded automatically (attestations: true default).
+
+  github-release:
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # required to create the GitHub release
+
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Create or update GitHub release
+        # Upsert rather than a bare `gh release create`: past releases in
+        # this repo were sometimes created by hand around the same tag, and
+        # a hard `create` would fail outright if one already exists for
+        # $GITHUB_REF_NAME. Attempt create first and fall back to upload on
+        # failure, instead of probing with a separate `gh release view` --
+        # same upsert semantics, one API call short.
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "$GITHUB_REF_NAME" \
+            --repo "$GITHUB_REPOSITORY" \
+            --title "$GITHUB_REF_NAME" \
+            --generate-notes \
+            dist/* \
+            || gh release upload "$GITHUB_REF_NAME" --repo "$GITHUB_REPOSITORY" --clobber dist/*