Release validation#

Release candidates use a prerelease version such as 2.3.0rc1 in pyproject.toml and a matching changelog entry. Module maturity labels and performance claims remain separate from the package version.

Pull-request checks#

Relevant pull requests run the Python 3.11–3.13 test matrix on Linux, macOS, and Windows, minimum runtime dependencies, quality checks, numerical benchmark comparisons, and repeated API stability checks. The wheel workflow builds Linux x86_64, Windows AMD64, macOS Intel, and macOS arm64 packages for the three Python versions. Hardware-dependent timing ratios are recorded as evidence; the new LS/affine comparisons fail on numerical disagreement rather than requiring a universal speedup.

Combined workflow timings use calibrated batches and alternating paired samples; their artifacts include raw measurements and variability. Check these diagnostics when a timing threshold fails. Numerical failures remain blocking, and a passing timing rerun alone does not resolve the original failure. The measurement protocol is described in Performance evidence.

Every wheel is installed outside the checkout before scripts/check_installed_wheel.py runs. This imports the actual native extension, compares cubic LS with the independent Python projection, compares affine backends and coefficient preparation across modes and precisions, and checks packaged data and the demo entry point.

Validation without publication#

In GitHub Actions, manually run Validate and publish release on the desired branch or revision. Manual dispatch runs all validation and builds artifacts; it never enters the publishing job. Once this workflow is on the default branch, the Actions interface exposes its manual-run control.

The release workflow calls the test, quality, stability, and wheel workflows using local references, so they run from the same commit. This is the GitHub local reusable-workflow contract. The artifact audit requires all twelve distinct Python/platform combinations, matching filename and package metadata versions, a native binary and packaged data in each wheel, and a source archive containing the wheel checks without Python cache files.

Local validation can supplement the hosted checks:

python -m pytest -q
python -m build
python scripts/audit_release_artifacts.py --version 2.3.0

Install the resulting wheel into a fresh virtual environment and run scripts/check_installed_wheel.py with that environment’s Python. The script rejects source imports and verifies the version against this checkout. An audit without --complete validates a local build; it does not claim coverage of the full release wheel matrix.

Visual documentation checks#

Build the complete gallery when reviewing thumbnails, figures, or branding:

python -m pip install -e ".[docs]"
python -m sphinx -b html docs docs/_build/html -W --keep-going

Open examples.html and the module gallery pages in both themes and at a narrow viewport. Every example should have its own generated preview. The quality workflow’s parse-only build (plot_gallery=0) checks documentation structure but creates placeholder thumbnails; a build that executes only a subset of examples is also not a complete visual preview. Use a fresh checkout for release screenshots: generated thumbnails under docs/auto_examples can retain placeholders from a previous parse-only run.

Publishing#

After review and successful checks, finalize the version and changelog, then create a matching v<version> tag on the reviewed commit. A tag such as v2.3.0rc1 publishes a prerelease; v2.3.0 publishes the stable release. Tagging starts validation again. The publishing job requires the complete tests, quality checks, standard stability soak, and artifact audit to succeed. Only this publishing job has permission to request the PyPI identity token.

Do not bypass failed checks with an unvalidated upload. Diagnose numerical failures before changing tolerances; record legitimate precision-dependent contracts and keep independent accuracy checks. Preserve benchmark results with their environment and revision so release claims remain reproducible.