Deltakit Release Procedure#

A new version of Deltakit is released on a regular basis. Only stable releases are currently supported.

Stable Releases#

Stable releases are performed whenever new features are implemented or bug fixes are made. The target audience of stable releases is typical users. Semantic versioning communicates whether releases include any backward compatible changes so that users can decide when/whether to upgrade.

A stable release currently consists of:

  • a version tag (human-readable label) associated with a commit,

  • assets published to PyPI (which gets added to the “Release history” there), and

  • assets published to “Releases” on our GitHub repo.

  • documentation, currently published using GitHub pages.

“Assets” currently refers to wheels (pre-built Python package format) and sdists (“source distribution”) of deltakit and all component libraries.

A release is accompanied by release notes. Draft release notes are automatically compiled by Python Semantic Release from the commit messages, and these are manually reviewed and edited before publication.

To perform a release, the release manager needs to go through the following steps:

  1. Create release notes. On main:

  2. Sync the release group:

uv sync --python 3.13 --group release

  1. Update release notes inCHANGELOG.md:

uv run --no-sync semantic-release -vv version --no-push --no-commit --no-tag

  1. Increment the version number in all subpackages pyproject.toml files:

uv run --no-sync python tools/propagate_version.py

  1. Update the packages depending on a deltakit-* subpackage to the new version (e.g., deltakit-explorer depends on deltakit-core, deltakit-circuit and deltakit-decode and these dependencies should reflect the new deltakit version).

  2. Generate a licenses.confluence file:

uv run --no-sync pip-licenses --format=confluence  --output-file licenses.confluence

Hand-edit it if necessary, and check that the deltakit-* subpackages versions changed to the released version.

  1. Create a release branch with naming format release/v<version number>. On that branch, commit the previous changes and open a PR targeting main. The PR undertakes the review/approval process. Before merge, any final changes merged to main during the review process can be added by editing draft notes auto-generated by semantic release (step 1.).

  2. Update the version tag. After merge, the release manager checks out the commit to be released (typically the latest main after the release note PR merges), creates a tag (e.g. git tag v0.4.0), and pushes the tag to GitHub (git push origin v0.4.0).

  3. Trigger the stable release workflow. On the tagged commit (i.e., click on “Run workflow”, and pick an entry in the “Tags” tab when selecting a value for “Use workflow from”), trigger the “Build, test, and publish stable wheels” on GitHub Actions here. It builds, tests and publishes the artefacts to PyPI and GitHub, and it renders and uploads the documentation to GitHub pages.

The latest stable version of deltakit can be installed with pip install deltakit.