Releasing
The version number is single-sourced in
oscal/_version.py.
pyproject.toml declares dynamic = ["version"] and reads that literal at build time, and
oscal/__init__.py imports it so oscal.__version__ is correct at runtime without a
reinstall. Changing the version is a one-line edit to oscal/_version.py.
Release steps
- Bump the version in
oscal/_version.py(e.g.__version__ = "4.1.0"). Commit. - Tag with a matching
v-prefixed tag:git tag v4.1.0 && git push origin v4.1.0. The tag’s digits must equal_version.py(the publish workflow enforces this). - Publish a GitHub Release for that tag. Publishing (not just creating the tag) is what
triggers
publish.yml.
What the workflows do
On every push to main (ci.yml) — before you tag — the sync-release-assets job
refreshes the OSCAL support database and the API docs and rebuilds the documentation site,
so those are current ahead of a release.
When the Release is published (publish.yml):
build— verifies the release tag matchesoscal/_version.py(fails fast on a mismatch), then builds the sdist and wheel and runstwine check.sbom— installs the built wheel into a clean runtime-only environment, generates the CycloneDX SBOM and regeneratesTHIRD-PARTY-LICENSES.md, and attaches both to the Release. See SBOM.publish— uploads to PyPI via OIDC trusted publishing. It declaresneeds: [build, sbom], so a version is never published to PyPI unless its SBOM was generated and attached first. Build provenance (PEP 740 attestations) is emitted by the publish action and shown on PyPI.
If the tag and _version.py disagree
The build job stops the release with an error. Fix whichever is wrong — bump
oscal/_version.py to match the tag, or delete and re-create the tag to match the file —
and publish the Release again.