ci: run the test suite and documentation build on every push and pull request

[EternalTime]

Intent

Make GitHub run pyEDW's tests automatically on every push and every pull request so nothing lands untested. Add a GitHub Actions workflow at .github/workflows/tests.yml that installs the library exactly the way the repository's own published instructions describe - using the 'test' extra via 'pip install -e ".[test]"' rather than installing pytest by hand - runs the suite with pytest, and does so across the FULL range of Python versions the repository claims to support. That claim is read from pyproject.toml (requires-python >=3.8 plus classifiers through 3.14) and the README ('Requires Python 3.8+'), so the matrix is deliberately 3.8 through 3.14 rather than a convenient subset; do not suggest trimming it. A second job builds the manual with the 'docs' extra so a broken documentation build is caught too. The workflow was deliberately kept boring: only actions/checkout and actions/setup-python, a plain version matrix, no dependency caching, no third-party actions. fail-fast is off on purpose so one bad version does not hide the others. The venv steps in the published recipe are intentionally omitted because setup-python already provides an isolated interpreter. This was verified before opening the PR: the branch was pushed and run 32224265656 came back green - all seven Python versions passed 11 tests each (3.8 resolves numba 0.58.1, 3.14 resolves current numba) and the docs job built successfully, which confirms the claimed 3.8-3.14 range is真 and means the published install instructions needed no correction. Scope is deliberately limited to adding the workflow file and nothing else. PR title must be one plain sentence.

What Changed

• Adds .github/workflows/tests.yml, which triggers on every push and pull request and installs the package with pip install -e ".[test]" (the same test extra the published instructions use) before running pytest.
• Runs the suite across the full supported range from pyproject.toml and the README - Python 3.8 through 3.14 - with fail-fast: false so one failing version does not mask the rest, using only actions/checkout and actions/setup-python with no dependency caching or third-party actions.
• Adds a second docs job that installs the docs extra and runs make html in docs/, plus a top-level permissions: contents: read block so the workflow token is read-only.

Run 32224265656 on this branch came back green: all seven Python versions passed 11 tests each and the docs job built successfully, so the claimed 3.8-3.14 range holds and the install instructions needed no correction.

Risk Assessment

✅ Low: The branch adds a single self-contained CI workflow file with no production-code impact, satisfies every source-verifiable acceptance criterion, and the review fix was a minimal least-privilege contents: read addition that leaves all other behavior untouched.

Testing

I validated the workflow the way an end user experiences it - through GitHub Actions itself - rather than only reading the YAML. The branch's run 32224265656 is green with all seven matrix jobs (3.8 through 3.14) plus the docs job, and I captured the Actions run page as a screenshot along with the Python 3.8 job log showing numba 0.58.1 resolving and 11 tests passing, which substantiates the deliberately full 3.8-3.14 range. I then reproduced both jobs' exact recipes locally at the target commit - pip install -e ".[test]" + pytest (11 passed) and pip install -e ".[docs]" + make html (build succeeded) - confirming the published extras recipe is sufficient with no hand-installed pytest, and parsed the target-commit YAML to confirm the triggers, permissions block, fail-fast off, and the checkout/setup-python-only step list. Two limits worth noting: the green run is for a6077aa, so the review commit's inert permissions: contents: read addition has not itself been run on GitHub yet, and only the push trigger has fired in a real run - the pull_request half is declared but will first execute when the PR opens, both of which the pipeline's own push and CI phases cover. Everything passed; the temporary venv and generated docs/_build, .pytest_cache, egg-info, and __pycache__ artifacts were removed and the worktree is clean.

• Evidence: GitHub Actions run page - all 7 Python versions + docs green

Evidence: CI job results for run 32224265656

run: 32224265656 status: completed conclusion: success branch: fm/ci-pyedw event: push jobs: docs success test (3.8) success test (3.9) success test (3.10) success test (3.11) success test (3.12) success test (3.13) success test (3.14) success

run:
  id: 32224265656
  title: Run the test suite and documentation build on GitHub for every push a…
  status: completed
  conclusion: success
  workflow: tests
  branch: fm/ci-pyedw
  created: 10m ago
jobs[8]{id,name,status,conclusion}:
  95980673345,docs,completed,success
  95980673494,test (3.13),completed,success
  95980673565,test (3.8),completed,success
  95980673571,test (3.10),completed,success
  95980673572,test (3.9),completed,success
  95980673577,test (3.11),completed,success
  95980673585,test (3.14),completed,success
  95980673696,test (3.12),completed,success

Evidence: Python 3.8 CI job - oldest supported version resolves and passes

test (3.8) Install Downloading numba-0.58.1-cp38-cp38-manylinux2014_x86_64.whl (3.7 MB)
test (3.8) Install Successfully installed ... numba-0.58.1 numpy-1.24.4 pyEDW-0.1.0 pytest-8.3.5 scipy-1.10.1 ...
test (3.8) Run tests = test session starts ==
test (3.8) Run tests platform linux -- Python 3.8.18, pytest-8.3.5, pluggy-1.5.0
test (3.8) Run tests configfile: pyproject.toml
test (3.8) Run tests collected 11 items
test (3.8) Run tests == 11 passed in 9.29s ==

Evidence: Local reproduction of the test job recipe

$ pip install -e ".[test]" Successfully installed ... numba-0.67.0 numpy-2.5.2 pyEDW-0.1.0 pytest-9.1.1 scipy-1.18.0 ... $ pytest platform darwin -- Python 3.14.5, pytest-9.1.1, pluggy-1.6.0 configfile: pyproject.toml collected 11 items tests/test_metrics.py ..... [ 45%] tests/test_model.py ...... [100%] = 11 passed in 10.64s ==

$ python --version
Python 3.14.5

$ pip install -e ".[test]"
Using cached pillow-12.3.0-cp314-cp314-macosx_11_0_arm64.whl (4.8 MB)
Using cached pyparsing-3.3.2-py3-none-any.whl (122 kB)
Using cached python_dateutil-2.9.0.post0-py2.py3-none-any.whl (229 kB)
Using cached six-1.17.0-py2.py3-none-any.whl (11 kB)
Using cached numba-0.67.0-cp314-cp314-macosx_12_0_arm64.whl (2.7 MB)
Using cached llvmlite-0.49.0-cp314-cp314-macosx_12_0_arm64.whl (40.5 MB)
Using cached pytest-9.1.1-py3-none-any.whl (386 kB)
Using cached pluggy-1.6.0-py3-none-any.whl (20 kB)
Using cached iniconfig-2.3.0-py3-none-any.whl (7.5 kB)
Using cached pygments-2.21.0-py3-none-any.whl (1.3 MB)
Using cached scipy-1.18.0-cp314-cp314-macosx_14_0_arm64.whl (20.4 MB)
Building wheels for collected packages: pyEDW
  Building editable for pyEDW (pyproject.toml): started
  Building editable for pyEDW (pyproject.toml): finished with status 'done'
  Created wheel for pyEDW: filename=pyedw-0.1.0-0.editable-py3-none-any.whl size=6619 sha256=2131ec9fb75a7cf3733d54fd6cd902e3bbfd9e0260e764caade0c75526c122ba
  Stored in directory: /private/var/folders/ym/vnmfjh5n7dn2vdzdgy7zrbjh0000gn/T/pip-ephem-wheel-cache-nnb1z0l3/wheels/c2/2a/f4/90a556abef7de5b62e30572f6a1477b90b5f14bb18c1c926a9
Successfully built pyEDW
Installing collected packages: six, pyparsing, pygments, pluggy, pillow, packaging, numpy, llvmlite, kiwisolver, iniconfig, fonttools, cycler, scipy, python-dateutil, pytest, numba, contourpy, matplotlib, pyEDW

Successfully installed contourpy-1.3.3 cycler-0.12.1 fonttools-4.63.0 iniconfig-2.3.0 kiwisolver-1.5.0 llvmlite-0.49.0 matplotlib-3.11.1 numba-0.67.0 numpy-2.5.2 packaging-26.3 pillow-12.3.0 pluggy-1.6.0 pyEDW-0.1.0 pygments-2.21.0 pyparsing-3.3.2 pytest-9.1.1 python-dateutil-2.9.0.post0 scipy-1.18.0 six-1.17.0

$ pytest
============================= test session starts ==============================
platform darwin -- Python 3.14.5, pytest-9.1.1, pluggy-1.6.0
rootdir: /Users/owlshome/.no-mistakes/worktrees/20c9704a8810/01M0CC3YG92CJK173RB3YAB3ZV
configfile: pyproject.toml
collected 11 items

tests/test_metrics.py .....                                              [ 45%]
tests/test_model.py ......                                               [100%]

============================= 11 passed in 10.64s ==============================

Evidence: Local reproduction of the docs job recipe

$ pip install -e ".[docs]" Successfully installed ... sphinx-9.1.0 sphinx-copybutton-0.5.2 sphinx-rtd-theme-3.1.0 sphinxcontrib-bibtex-2.7.0 ... $ cd docs && make html writing output... [100%] theory generating indices... genindex py-modindex done build succeeded. The HTML pages are in _build/html.

$ pip install -e ".[docs]"
    Found existing installation: pyEDW 0.1.0
    Uninstalling pyEDW-0.1.0:
      Successfully uninstalled pyEDW-0.1.0

Successfully installed Jinja2-3.1.6 MarkupSafe-3.0.3 alabaster-1.0.0 babel-2.18.0 certifi-2026.7.22 charset_normalizer-3.5.1 docutils-0.22.4 idna-3.19 imagesize-2.0.0 latexcodec-3.0.1 pyEDW-0.1.0 pybtex-0.26.1 pybtex-docutils-1.0.3 requests-2.34.2 roman-numerals-4.1.0 snowballstemmer-3.1.1 sphinx-9.1.0 sphinx-copybutton-0.5.2 sphinx-rtd-theme-3.1.0 sphinxcontrib-applehelp-2.0.0 sphinxcontrib-bibtex-2.7.0 sphinxcontrib-devhelp-2.0.0 sphinxcontrib-htmlhelp-2.1.0 sphinxcontrib-jquery-4.1 sphinxcontrib-jsmath-1.0.1 sphinxcontrib-qthelp-2.0.0 sphinxcontrib-serializinghtml-2.0.0 urllib3-2.7.0

$ cd docs && make html
Writing evaluated template result to /Users/owlshome/.no-mistakes/worktrees/20c9704a8810/01M0CC3YG92CJK173RB3YAB3ZV/docs/_build/html/_static/copybutton.js
copying static files: done
copying extra files... 
copying extra files: done
copying assets: done
writing output... [ 12%] api/pyEDW
writing output... [ 25%] applet
writing output... [ 38%] getting_started
writing output... [ 50%] guide_metrics
writing output... [ 62%] guide_model
writing output... [ 75%] index
writing output... [ 88%] license
writing output... [100%] theory

generating indices... genindex py-modindex done
highlighting module code... [ 33%] pyEDW.figures
highlighting module code... [ 67%] pyEDW.metrics
highlighting module code... [100%] pyEDW.model

writing additional pages... search done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded.

The HTML pages are in _build/html.

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

🔧 **Review** - 3 issues found → auto-fixed ✅

• ℹ️ .github/workflows/tests.yml:38 - The docs job runs make html without SPHINXOPTS: -W, so Sphinx warnings do not fail the build. Broken cross-references, missing toctree entries, unresolved footcite keys against docs/references.bib, and autodoc import warnings all exit 0, so the job only catches hard build errors rather than a genuinely broken manual. Adding env: SPHINXOPTS: -W to the step would close the gap, but it changes how strict CI is, so it is the author's call.
• ℹ️ .github/workflows/tests.yml:3 - on: push: and pull_request: are both unfiltered, so a branch pushed in this repo and then opened as a PR runs all 8 jobs twice per push, and tag pushes also trigger full runs. This matches the stated intent ("every push and every pull request") and is free on a public repo; noting the tradeoff only. Narrowing to push: branches: [main] plus pull_request:, or adding a concurrency group to cancel superseded runs, would halve the work if it ever becomes a concern.
• ℹ️ .github/workflows/tests.yml:1 - No top-level permissions: block, so the GITHUB_TOKEN handed to actions/checkout inherits the repository default, which may be read/write. Neither job needs write access. Adding permissions:\n contents: read at the workflow level is standard least-privilege hardening and does not conflict with the "only checkout and setup-python, no third-party actions" constraint.

🔧 Fix: Add top-level contents:read permissions to tests workflow
✅ Re-checked - no issues remain.

✅ **Test** - passed

✅ No issues found.

• gh-axi run list --workflow tests.yml and gh-axi run view 32224265656 - confirmed conclusion success for jobs test (3.8) through test (3.14) and docs on branch fm/ci-pyedw
• gh-axi run view 32224265656 --job 95980673565 --log - inspected the Python 3.8 job log; resolves numba 0.58.1 / numpy 1.24.4 on CPython 3.8.18 and reports 11 passed in 9.29s
• Captured a full-page screenshot of https://github.com/EternalTime/pyEDW/actions/runs/32224265656 via chrome-devtools-axi screenshot --full-page showing all 8 jobs green
• Local reproduction of the test job recipe in a throwaway venv: pip install -e ".[test]" then pytest -> 11 passed (Python 3.14.5)
• Local reproduction of the docs job recipe: pip install -e ".[docs]" then make html in docs/ -> build succeeded
• Parsed .github/workflows/tests.yml at target commit 6201c68 with PyYAML to confirm push/pull_request triggers, permissions: contents: read, fail-fast: false, the 3.8-3.14 matrix, and only actions/checkout@v4 + actions/setup-python@v5 with no caching
• git status --porcelain --ignored after cleanup - worktree clean, no build artifacts left behind

⚠️ **Document** - 1 info

• ℹ️ docs/getting_started.rst:78 - Judgment call, no edit made: the repository now runs tests and the docs build automatically on every push and PR, but nothing documents that contract to contributors. There is no CONTRIBUTING.md to own contribution mechanics, and the placement policy says not to create a new documentation surface merely to close a perceived gap, so I did not add one. The 'Running the tests' section of docs/getting_started.rst (the authority on install/test mechanics per README) would be the natural owner for a one-line note that CI runs the same commands across Python 3.8-3.14, if the author wants it documented. Nothing existing was made stale, so this is optional follow-up rather than a defect.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.