Deltakit Release Procedure#

The release procedure is currently in discussion in gh-55; here is a working summary.

There are three kinds of releases:

  • stable release - published on a regular schedule from main,

  • “nightly” release - published automatically whenever commits are added to main, and:

  • alpha release - published as-needed, primarily for testing of a feature branch.

Stable Releases#

Stable releases are performed on a fixed (fortnightly) schedule and as-needed whenever critical 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.

“Nightly” Releases#

Contrary to the name, “nightly” releases are performed every time commits are added to main- typically when a PR merges. The target audience of “nightly” releases is power users who want access to features and bug fixes as soon as they become available in main. The base version number is determined as with stable releases, but a suffix of the form .devYYYYMMDDhhmmss is appended to denote the fact that it is a development release and to order the development releases chronologically.

A nightly release currently consists only of assets published to PyPI. Currently, there are no release notes, no tag is generated, no assets are published on GitHub, and the documentation is not rendered. (However, when the repository becomes public and documentation is migrated to Read the Docs, documentation associated with the main branch will be available there.)

These releases are performed automatically, and there is no way to trigger one besides adding commits to main. The workflow associated with nightly releases is “Build, test, and publish nightly wheels”, nightly_release.yml).

The latest “nightly” version of deltakit can be installed by using pip with the --pre option, specifying the desired version number; e.g., pip install deltakit --pre 0.4.0.dev20250904222833.

Alpha Releases#

Alpha releases are typically generated on demand from a feature branch. The target audience of “alpha” releases is power users and alpha testers who need access to a particular feature or bug fix before it becomes available in main. The base version number is determined as with stable releases, but a suffix of the form aYYYYMMDDhhmmss is appended to denote the fact that it is an alpha release and to order the alpha releases chronologically.

An alpha release currently consists of a tag and assets published to PyPI. Currently, there are no release notes, no assets are published on GitHub, and the documentation is not rendered. (However, when the repository becomes public and documentation is migrated to Read the Docs, documentation associated with the feature branch will be available there. Also, the PR associated with the feature branch serves to document the relevant changes.)

To perform an alpha release, the release manager triggers the alpha release workflow on the desired commit (“Build, test, and publish alpha wheels” on GitHub Actions, alpha_release.yml). This builds and publishes the artefacts to PyPI, and it associates a tag with the commit on GitHub.

The latest alpha version of deltakit can be installed by using pip with the --pre option, specifying the desired version number; e.g., pip install deltakit --pre 0.4.0a20250904222833.