Versioning Policy

Docs-Release Parity

Docs versions must correspond to code tags:

  • The versioned docs deploy is triggered only by a pipeline triggered by git tag v0.8.x in the source repo.

  • No docs version exists without a corresponding code tag.

Version Identifiers

Identifier

Meaning

master

Latest commit on master (dev snapshot)

v0.7, v0.8, …

Tagged releases

Deployment

# Deploy tagged version (CI only — runs sphinx-multiversion then ghp-import):
make docs-sphinx-multiversion
ghp-import -n -p -f docs/_sphinx_build/multiversion/ -b gh-pages

# Deploy dev snapshot (CI only — runs make docs then ghp-import):
make docs
ghp-import -n -p -f docs/_sphinx_build/html/ -b gh-pages

Current Implementation Notes

  • sphinx-multiversion (configured in docs/conf.py) builds one HTML tree per matching Git tag/branch and writes each to a subdirectory of the output root named by the ref.

  • docs/releases/changelog.md tracks unreleased deltas until next tag.

  • This repository currently documents and tests the policy; release tagging/deploy execution happens in the release workflow context.

  • MkDocs and mike are retired (S-PR7). mkdocs.yml and requirements.txt are archived as mkdocs.yml.archived and requirements.txt.archived.

Evidence

  • docs/conf.py (smv_tag_whitelist, smv_branch_whitelist, smv_outputdir_format)

  • docs/requirements-sphinx.txt (sphinx-multiversion==0.2.4, ghp-import==2.1.0)

  • docs/releases/changelog.md

  • Makefile docs targets (docs, docs-serve, docs-gen, docs-sphinx-multiversion)

See Also