Release and Versioning#
This page summarizes the practical release flow used in this repository.
1. Prepare release content#
Before tagging:
ensure tests pass;
decide and record the Conda route in
devtools/conda-build/release_plan.toml;run the full Python/platform matrix on the exact candidate commit;
ensure public API contract tests pass;
ensure docs build;
ensure README and docs reflect actual behavior;
ensure
CHANGELOG.mdhas release notes for the target version;ensure
devguide/roadmap.mdreflects delivered vs in-progress milestones;ensure support/deprecation notes are updated when compatibility changed;
verify ignored/generated files are not accidentally tracked.
2. Commit and push release-ready state#
Create coherent commits and push main.
3. Create and push tag#
Use canonical three-part tags (for example 0.2.0) without a v prefix or
prerelease suffix. The tag must identify the commit that passed the release
gates. Candidate testing takes place in the Conda staging label; it does not
create a public prerelease tag. Follow the two procedures in
devguide/conda_release_routes.md: an unstaged release can publish Conda
automatically after its preflight, while a staged release must promote the
exact tested file and SHA-256. Do not re-upload the staged filename.
4. Post-tag validation#
After pushing a tag:
verify release badge/version links;
verify the exact public Conda coordinate and digest independently;
verify the public Zenodo archival record and file inventory when required;
verify docs references to release when applicable;
confirm no local drift remains.
5. Pre-RC and Stabilization Quality Gates (0.8.0/0.9.x/0.10.x)#
When preparing release candidates:
accept only bug fixes and documentation consistency changes;
avoid feature additions unless they unblock release quality;
require explicit migration notes for any contract-affecting change;
keep migration notes centralized in
CHANGELOG.md;keep contract tests green before tagging.