Releasing

Checklist for preparing and verifying a Stratax release. The current candidate is 0.4.0rc1; updating the repository and rehearsing the build do not publish it.

Version Updates

Update all user-visible version references together:

pyproject.toml project version
CMakeLists.txt project VERSION (numeric base only)
bindings/module.cpp PyVersion
docs/Doxyfile PROJECT_NUMBER
docs/mainpage.md footer
docs/guides/CHANGELOG.md

For this candidate, the Python package, module, Doxygen project number, and main page use 0.4.0rc1. CMake's project VERSION accepts numeric components, so it uses 0.4.0. The prerelease suffix belongs to the full Python version and the eventual v0.4.0rc1 tag.

Keep the changelog focused on public behavior: new APIs, changed behavior, bug fixes, docs updates, and known limitations. Move completed changes into a dated candidate entry and leave an empty Unreleased section. Mark prepared notes as pending until publication succeeds.

Install the validation dependencies in the active Python 3.10-or-newer environment. Check source version agreement, then validate the intended tag without creating it:

python -m pip install packaging "tomli; python_version < '3.11'"
python scripts/check-release-version.py
python scripts/check-release-version.py --tag v0.4.0rc1

The conditional dependency supplies TOML parsing on Python 3.10; newer Python versions use the standard library.

The checker requires a canonical Python version and verifies it against PyVersion, Doxygen's project number, the main page footer, the changelog entry, and CMake's numeric base version. The optional --tag must match the full version with a leading v.

Pre-Release Checks

Run the release automation's validation tests:

python -m unittest discover -s tests/automation -p 'test_*.py'

Run the C++ build and tests:

cmake -S . -B build
cmake --build build --config Release
ctest --test-dir build -C Release --output-on-failure

Run Python tests:

python -m pip install -e ".[dev]"

python -m pytest tests/python

Run representative examples:

python examples/python/vector.py
python examples/python/matrix.py
python examples/python/tensor.py
python scripts/check-doc-examples.py
python scripts/check-headers.py

The C++ example checker uses GCC/Clang-style compiler flags. On an MSVC-only setup, run --python locally and run --cpp on a GCC/Clang host. Configure single-config generators with -DCMAKE_BUILD_TYPE=Release when required.

Documentation

GitHub Pages documentation is generated by .github/workflows/docs.yml using docs/Doxyfile. Source docs should be updated before release; generated HTML does not need hand edits.

For local verification:

doxygen docs/Doxyfile

Doxygen warnings fail the build. Check that the generated landing page includes the current version, user guide, examples, roadmap, and developer docs.

Packaging

Before building distributions, confirm the Python package contains the public exports and typing files:

python/stratax/__init__.py
python/stratax/_core.pyi
python/stratax/py.typed

Local copied extension binaries such as _core.cp313-win_amd64.pyd are build artifacts and should remain ignored by Git. The release wheel should receive the freshly built _core extension through the CMake install rule.

Build source and wheel distributions from a clean checkout:

python -m pip install --upgrade build twine
python -m build
python -m twine check --strict dist/EXACT_WHEEL_FILENAME.whl dist/EXACT_SDIST_FILENAME.tar.gz
python scripts/check-release-artifacts.py --version 0.4.0rc1 dist/EXACT_WHEEL_FILENAME.whl dist/EXACT_SDIST_FILENAME.tar.gz

Replace the artifact placeholders with the files just built. The artifact checker validates their versions and required package contents, including the typing stub and marker. twine check --strict validates distribution metadata and treats its warnings as failures.

Install the wheel matching the active interpreter and platform into a fresh environment before testing it:

python -m pip install --force-reinstall dist/EXACT_WHEEL_FILENAME.whl "pytest>=8"

python -c "import stratax; print(stratax.__version__)"

Run the installed-package check and examples from outside the source import path:

python -I scripts/check-installed-package.py
python scripts/check-doc-examples.py --python --installed
python scripts/check-sdist.py dist/EXACT_SDIST_FILENAME.tar.gz

The installed-package checker verifies distribution provenance, agreement between package metadata and the runtime version, and the installed typing files before running tests. The source checker creates another fresh environment, installs that archive, and runs the tests and documentation examples contained in it. See Verification for the complete CI gates.

Release Rehearsal

After pushing the prepared commit, manually run the Release workflow on its ordinary branch. This builds and tests the actual release wheels on Linux, Windows, and macOS for the selected CPython 3.10–3.14 interpreters, and builds and tests the source distribution. Confirm all build and validation jobs pass, then download their artifacts and inspect the candidate's metadata and contents. Record the commit and workflow run used for the rehearsal.

Branch dispatch skips publication. Dispatching the workflow on a v* tag can publish, so select the branch when rehearsing. Green source-build CI alone does not establish that the release wheel matrix passed.

Publish

The tag-triggered .github/workflows/release.yml verifies the source versions and tag, builds wheels and an sdist, tests each wheel through cibuildwheel, builds and tests an installed package from the sdist, and validates the combined artifacts before publishing them to PyPI. Create the new version tag only after the candidate's tests, documentation, and release rehearsal pass and publication is intended. The tag below is a placeholder; replace it with the prepared full version, including its prerelease suffix.

git tag vX.Y.ZrcN

git push origin vX.Y.ZrcN

After publishing, verify the PyPI page, install the exact released version in a fresh environment, and confirm the GitHub Pages workflow completes successfully. Remove the changelog's pending-publication note only after publication is confirmed.