Home/Release Process

Release Process

Versioning and release workflow

Where the version lives

The release version has a single source of truth in the root Cargo.toml:

  • [workspace.metadata.workspaces].version — authoritative version. The release workflow and tooling read it (e.g. cargo metadata | jq -r '.metadata.workspaces.version').
  • [workspace.package].version stays "0.0.0" as a placeholder; cargo-workspaces uses the metadata version when publishing.
Cargo.toml
Root workspace manifest — bump [workspace.metadata.workspaces].version only for a release.

Cutting a release

Bump the version under [workspace.metadata.workspaces], merge (e.g. release PR), then the CI workflow:

  • Reads the version from cargo metadata (no sed or in-repo string replacement).
  • Builds binaries, publishes crates (cargo ws publish), and creates the GitHub release with that version.

Binaries, libraries, and types

  • Binaries (merod, meroctl) — displayed version comes from build-time env vars in each crate’s build.rs (MEROD_VERSION, MEROCTL_VERSION), derived from workspace metadata plus git describe/commit.
  • Libraries that need a release string (e.g. bundle minRuntimeVersion) expose CALIMERO_RELEASE_VERSION from build.rs, sourced from [workspace.metadata.workspaces].version.
  • The Version type and related protocol types live in calimero_primitives::version.
Example metadata bump
[workspace.metadata.workspaces]
version = "1.2.3" # or e.g. "0.10.0-rc.43"

CI workflow

Pushes to master run the main CI pipeline. The release workflow reads the version from root Cargo.toml workspace metadata (cargo metadata), builds merod and meroctl binaries for Linux and macOS, publishes workspace crates with cargo-workspaces, and creates a GitHub release attaching those artifacts.

Docker images

The merod image is published to ghcr.io/calimero-network/merod. Images are tagged with the release version; edge tracks the latest master build.

Changelog

Release notes are driven by CHANGELOG.md at the repository root. It follows the Keep a Changelog format and should be updated in the same PR that bumps the workspace version.