Skip to content

Release process

To release a new version, create a GitHub release ⧉. This triggers all necessary pipelines.

Note

Specify a new tag version and (optionally) release title. Changelog will be automatically updated by the pipelines.

Caution

You must create GitHub release manually. Merging to main does not trigger package or documentation releases.

Versioning

This project uses a double versioning scheme based on Semantic Versioning ⧉:

  • Public version – The official release version (e.g., 1.2.0).
  • Python version – Automatically generated from commits and independent of the public version.

Rationale

Public versions are there to signify the release to the audience (mainly for marketing purposes), while the Python version ensures semantic consistency (needed by package users). This approach also enhances security by preventing automated tag pushes to main (no bot automerges).

Public version

Public releases follow Semantic Versioning ⧉ and trigger:

  • Package release to PyPI (for public repositories, versioned by Python version).
  • Documentation updates.
  • Artifact generation (e.g., Software Bill of Materials ⧉).

Python version

Managed automatically based on commit messages:

  • fix → Patch version update
  • feat → Minor version update
  • BREAKING (or feat!/fix!) → Major version update

Tip

Check out commition ⧉ for details about Python version calculations.

Artifacts

Releases include the following artifacts:

Important

Some artifacts depend on repository visibility, the more public the repository, the more artifacts are produced.

Note

Attestations of Python package SBOMs use hashes of RECORD files as inputs, see here ⧉ for more information about them.

Repository visibility and compliance

Visibility Artifacts produced Compliance level
Public All artifacts SLSA Level 3 ⧉
Enterprise No provenance, private attestations SLSA Level 3 ⧉
Private No attestations, limited artifacts SLSA Level 2 ⧉

Changelog

Generated via git-cliff ⧉ (configured in pyproject.toml) and:

  • The latest version's changelog becomes the release description.
  • Full CHANGELOG.md attached to the release
  • CHANGELOG.md inside the repository links to GitHub releases

The changelog includes:

  • Public version, date, and comparison link
  • Commit statistics (e.g., how many commits done by human vs bots, types of commit like security, tests, legal etc.)
  • Python changes (Breaking, Features, Fixes, Bots)
  • Other changes (same structure as Python changes)
  • Each commit includes message, author, and metadata (if available)

Tip

Read more about changelogs in the FAQ

Customization

This process can be adjusted by editing:

  • .github/workflows/release.yml

  • pyproject.toml:

    1. [tool.git-cliff] – Changelog settings

    2. [dependency-groups] → dev-security – changing SBOM dependencies

Important

Due to pipeline complexity, fine-tuning is more challenging, consult the source files if necessary.

Code sources

  • pyproject.toml
  • .github/workflows/release.yml
  • .github/workflows/release-upload.yml
  • .github/workflows/release-sarifs-reusable.yml
  • .github/workflows/release-sbom-attest-reusable.yml
  • .github/workflows/release-sbom-run-reusable.yml
  • .github/workflows/release-sboms-reusable.yml
  • .github/workflows/release-slsa-provenance-reusable.yml