Releasing

Releasing

Version Scheme

Published desktop, CLI, daemon, and runtimed Python artifacts share the same base version. Python release jobs stamp the wheel version from the Rust release source during the workflow, after cargo xtask bump has updated the checked-in version files.

Internal Compatibility Markers

Two independent version numbers (incrementing integers, not semver):

• Protocol version (PROTOCOL_VERSION in crates/notebook-protocol/src/connection/handshake.rs, re-exported by connection.rs): Wire compatibility. Validated by magic bytes preamble at connection time.
• Schema version (SCHEMA_VERSION in notebook-doc/src/lib.rs): Automerge document compatibility. Stored in doc root.

These evolve independently from each other and from the artifact version.

Bumping Versions

cargo xtask bump patch  # or minor, or major

This updates all versioned artifacts in lockstep (Rust crates, Python packages, frontend packages, plugin manifests, Tauri config) and runs cargo update -w to refresh Cargo.lock. See crates/xtask/src/bump.rs for the complete target list.

Commit the version bump, then tag to trigger the release.

Release Types

Stable Release

git tag v2.1.0-stable.202607020900
git push origin v2.1.0-stable.202607020900

Triggers release-stable.yml which:

1. Builds desktop app (macOS, Windows, Linux)
2. Builds runt CLI binaries
3. Builds Python wheels stamped to the base version from crates/runt/Cargo.toml
4. Publishes runtimed wheels to PyPI (stable)
5. Creates GitHub Release with all artifacts
6. Updates stable-latest Tauri updater channel
7. Posts to Discord

Nightly Release

Runs automatically at 9am UTC daily via release-nightly.yml, or manually via workflow dispatch.

• Desktop version gets -nightly.{timestamp} suffix
• Python wheels get alpha stamp: 2.0.1a202507150900 (PEP 440)
• App branded "nteract Nightly" with separate bundle ID
• GitHub Release marked as prerelease
• CLI binary named runt-nightly

Install nightly Python: pip install runtimed --pre

Python Release Policy

runtimed Python wheels ship from the stable and nightly release workflows. Nightly builds stamp the next patch alpha version (PEP 440), and stable builds stamp the base version from crates/runt/Cargo.toml. cargo xtask bump still updates python/runtimed/pyproject.toml; workflow stamping is a guardrail so a stale pyproject cannot publish the wrong wheel version.

Tag Reference

Protocol Version Change Procedure

1. Bump PROTOCOL_VERSION in crates/notebook-protocol/src/connection/handshake.rs
2. Update the PROTOCOL_V* string constant if the version string changes
3. Update crates/notebook-wire/AGENTS.md
4. Decide version bump type based on user impact

Magic bytes preamble rejects mismatched protocol versions at wire level, before JSON parsing.

Schema Version Change Procedure

1. Bump SCHEMA_VERSION in crates/notebook-doc/src/lib.rs
2. Add migration logic in daemon's doc loading path (detect old schema, convert in-place)
3. Update document schema comment in notebook-doc/src/lib.rs

Schema changes don't require a protocol bump because the wire format for sync frames stays the same.

CI Internals

release-common.yml accepts inputs:

• github_release_prerelease: true: applies PEP 440 alpha stamp to Python version
• github_release_prerelease: false: stamps Python version from crates/runt/Cargo.toml

Python wheels are always built (macOS arm64, macOS x64, Linux x64, Windows x64) and published.

Desktop version: {runt version}-{suffix}.{timestamp} stamped into tauri.conf.json and Cargo.toml at build time (not committed).

Trusted Publishing

PyPI uses OIDC trusted publishing (no API tokens). GitHub Actions workflow identity registered as trusted publisher on PyPI for runtimed package.

Pre-Release Checklist

• All version sources bumped and in sync
• cargo check passes (Cargo.lock updated)
• PROTOCOL_VERSION and SCHEMA_VERSION correct for this release
• CI is green on main
• Changelog-worthy items use conventional commit prefixes (feat, fix, perf)