Skip to content

versioning.md

Latest commit

 

History

History
130 lines (98 loc) · 5.85 KB

versioning.md

File metadata and controls

130 lines (98 loc) · 5.85 KB
Raw

Versioning policy

Spanda follows Semantic Versioning 2.0.0. Each release stream has its own version line — bump only the stream whose area changed.

Canonical roadmap milestones: ROADMAP.md

Independent release streams

Stream When to bump Manifests Release tag(s)
Workspace / CLI Language, compiler, runtime, CLI, core platform milestones Cargo.toml [workspace.package].version, root package.json, editor/vscode/, packages/lsp, packages/native, packages/web vX.Y.Z
Official SDKs New or changed REST/gRPC client methods; SDK API fixes (Rust + Python + TS bump together) crates/spanda-sdk/Cargo.toml, sdk/python/pyproject.toml, sdk/typescript/package.json, packages/sdk-python/pyproject.toml crates-sdk-vX.Y.Z, sdk-python-vX.Y.Z, npm-sdk-vX.Y.Z
Control Center desktop Tauri shell, embedded UI packaging, desktop-only fixes packages/control-center-desktop/package.json, src-tauri/Cargo.toml, tauri.conf.json desktop-vX.Y.Z
gRPC proto Additive or breaking RPC changes crates/spanda-api/proto/spanda/v1/control_center.proto (no tag — pin via GET /v1/version)

Rule: Do not bump SDK or desktop when only the workspace changes, and vice versa. Streams may diverge (for example workspace 0.6.3, SDK 0.5.8, desktop 0.6.3).

Semver component guide (per stream)

Component Increment when
Patch Bug fixes, regressions, small non-breaking polish within that stream's current release line
Minor Substantial additive features for that stream, or a roadmap milestone for workspace
Major Breaking public contracts for that stream; workspace v1.0 positioning

Workspace-specific milestones

Milestone / phase Bump
Bug fix in CLI / language / runtime patch (workspace)
Architecture hardening phase (no user-visible theme) patch or defer
Roadmap release milestone (v0.5, v1.0, …) minor (workspace)
Breaking language syntax or default CLI behavior major (workspace)

SDK-specific

Change Bump
New REST route wrappers / gRPC client methods (all three SDKs) minor or patch
SDK-only bug fix patch
Breaking public SDK API major

Desktop-specific

Change Bump
Tauri shell, updater, packaging, desktop UI wiring patch or minor
Breaking desktop install/upgrade path major

Automatic desktop bump: When a merged PR has a release:* label and changes Control Center paths (see scripts/control_center_paths_changed.sh), Auto release bumps the desktop stream with the same semver component and pushes desktop-v*.

Version display: Control Center UI shows vX.Y.Z in the sidebar; spanda control-center --version and spanda control-center status report the UI semver; GET /v1/version and GET /v1/instance include control_center_ui_version. Full reference: control-center-versioning.md.

Bump commands

# Workspace (CLI / platform) — updates CHANGELOG [Unreleased] → dated section
python3 scripts/bump_version.py minor --dry-run
python3 scripts/bump_version.py patch

# Official SDKs only (Rust + Python + TypeScript together)
python3 scripts/bump_version.py patch --stream sdk --dry-run
python3 scripts/bump_version.py minor --stream sdk

# Control Center desktop only
python3 scripts/bump_version.py patch --stream desktop --dry-run
python3 scripts/bump_version.py minor --stream desktop

Tag and push (only the stream you bumped)

# Workspace release
git tag v0.5.1 && git push origin v0.5.1

# SDK release (push all three tags)
git tag crates-sdk-v0.5.1 sdk-python-v0.5.1 npm-sdk-v0.5.1
git push origin crates-sdk-v0.5.1 sdk-python-v0.5.1 npm-sdk-v0.5.1

# Desktop release
git tag desktop-v0.5.1 && git push origin desktop-v0.5.1
Tag Triggers
vX.Y.Z cargo-dist Release (CLI installers)
crates-sdk-vX.Y.Z publish-sdk-rust.yml
sdk-python-vX.Y.Z publish-sdk-python.yml
npm-sdk-vX.Y.Z publish-sdk-typescript.yml
desktop-vX.Y.Z desktop-release.yml

Pre-release checks:

./scripts/verify_sdk_publish_ready.sh      # before SDK tags
./scripts/verify_desktop_release_ready.sh  # before desktop tag

Current versions (2026-07-08)

Stream Version Last tag
Workspace / CLI 0.6.3 v0.6.3
Official SDKs (published) 0.5.8 crates-sdk-v0.5.8, sdk-python-v0.5.8, npm-sdk-v0.5.8
Official SDKs (workspace line) 0.5.8 (aligned with published)
Control Center desktop 0.6.3 desktop-v0.6.3
Official registry packages 89 packages/registry/ → registry/index.json

Checklist

  • Identify which stream(s) actually changed
  • Bump only those streams (--stream workspace|sdk|desktop)
  • Add CHANGELOG.md notes for workspace releases; optional SDK/desktop notes under [Unreleased]
  • Push only the tag(s) for the stream you released
  • Do not bump a stream for unrelated work in another area

Related docs