Skip to content

Release Guide

obslog releases are automated and hardened: PyPI Trusted Publishing (OIDC — no long-lived tokens), signed build provenance attestations, and a published SBOM (REL-013, NFR-SEC-005).

Versioning

  • The package follows Semantic Versioning (REL-001).
  • The Record schema is versioned independently via schema_version (REL-002).
  • See API stability for the compatibility guarantees.

One-time setup

  1. On PyPI, configure Trusted Publishing for the project, pointing at this repository and the release.yml workflow (and a pypi environment).
  2. Ensure the repository has GitHub Pages enabled for the docs deploy.

Cutting a release

  1. Update the version and finalize the CHANGELOG.md Unreleased section under the new version heading.
  2. Open a PR; ensure CI is green (lint, strict types, tests across the Python matrix, benchmarks).
  3. Merge, then create a GitHub Release with a tag vX.Y.Z.
  4. The release.yml workflow then:
  5. builds the sdist and wheel,
  6. generates a CycloneDX SBOM,
  7. attests build provenance (Sigstore) for the artifacts,
  8. publishes to PyPI via Trusted Publishing.

Reaching 1.0

At 1.0 the public API and reserved Record schema are frozen (REL-003); subsequent breaking changes require a 2.0 and an ADR. Before tagging 1.0:

  • confirm the public surface in API stability is final,
  • confirm the Record and bundle JSON Schemas are final,
  • confirm docs cover every item in the documentation set.

Docs

Documentation is built with MkDocs and deployed by docs.yml on pushes to main:

python -m pip install -e ".[docs]"
mkdocs serve      # local preview
mkdocs build --strict