{"row":{"id":"ADR-025","title":"Per-crate semver via release-plz (publishable crates only)","file":"adr-025-per-crate-semver-release-plz.md","status":"accepted","date":"2026-04-16","cites":3,"supersedes":[],"superseded_by":[],"layers":["L5"],"tags":["semver","release-plz","publish","versioning"],"room":true},"pin":{"release_tag":"v0.107.0","commit":"5d61b7e13f1f6a10c17414f61146648f76bcf2bd"}}

[{"k":"h","depth":1,"text":"ADR-025: Per-crate semver + release-plz","id":"adr-025-per-crate-semver--release-plz"},{"k":"h","depth":2,"text":"Context","id":"context"},{"k":"p","inline":[{"k":"text","text":"Workspace currently uses single "},{"k":"code","text":"version = \"0.80.0\""},{"k":"text","text":" shared across all crates.\nWith the foundation "},{"k":"code","text":"publish = false"},{"k":"text","text":" strategy (ADR-022), only "},{"k":"code","text":"nika"},{"k":"text","text":" (binary)\nand future "},{"k":"code","text":"nika-sdk"},{"k":"text","text":" reach crates.io. Their semver should evolve independently\nof internal foundation crate refactors."}]},{"k":"h","depth":2,"text":"Decision","id":"decision"},{"k":"p","inline":[{"k":"strong","text":"Two-tier semver policy:"}]},{"k":"list","ordered":true,"items":[[{"k":"strong","text":"Foundation crates (`publish = false`)"},{"k":"text","text":" — keep workspace-shared version\n"},{"k":"code","text":"version.workspace = true"},{"k":"text","text":". Not published, semver irrelevant for ecosystem."}],[{"k":"strong","text":"Publishable crates (`nika`, future `nika-sdk`)"},{"k":"text","text":" — independent semver via\n"},{"k":"code","text":"release-plz"},{"k":"text","text":" GitHub workflow. Each crate has its own version field, bumped\nsemantically based on conventional-commit messages affecting that crate."}]]},{"k":"p","inline":[{"k":"strong","text":"Initial publishable versions:"}]},{"k":"list","ordered":false,"items":[[{"k":"code","text":"nika@0.80.0"},{"k":"text","text":" — binary republish from legacy v0.47.1 (yank old, fresh start\nwith diamond architecture once binary is wired)"}],[{"k":"code","text":"nika-sdk@0.1.0"},{"k":"text","text":" — first publication when v0.90 reaches stable surface"}]]},{"k":"p","inline":[{"k":"strong","text":"release-plz"},{"k":"text","text":" workflow runs on push-to-main, opens a PR with version bumps"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"CHANGELOG entries derived from commits, auto-publishes on PR merge."}]]},{"k":"h","depth":2,"text":"Consequences","id":"consequences"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"✅ "},{"k":"code","text":"nika"},{"k":"text","text":" binary version reflects user-facing API stability, not internal\nrefactor churn"}],[{"k":"text","text":"✅ "},{"k":"code","text":"nika-sdk"},{"k":"text","text":" ships independently — bug-fix release doesn't bump main binary"}],[{"k":"text","text":"✅ release-plz handles changelog generation + GitHub releases automatically"}],[{"k":"text","text":"❌ One-time workflow setup (~2h, one commit)"}],[{"k":"text","text":"⚠️ Conventional commit discipline becomes load-bearing (already mostly true\nvia commitlint hook)"}]]},{"k":"h","depth":2,"text":"Crates.io legacy cleanup (handled in Phase B.0)","id":"cratesio-legacy-cleanup-handled-in-phase-b0"},{"k":"code","lang":"text","text":"cargo yank nika-core@0.74.0      # diamond renames it; legacy abandoned\ncargo yank nika-event@0.74.0     # legacy\ncargo yank nika-engine@0.47.1    # legacy, rebranded as nika\n# nika@0.47.1 stays; republish at v0.80+ when binary is wired"},{"k":"h","depth":2,"text":"Reference","id":"reference"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"release-plz docs: "},{"k":"link","text":"https://release-plz.ieni.dev/","href":"https://release-plz.ieni.dev/"}],[{"k":"text","text":"ADR-022 (publish=false strategy)"}],[{"k":"code","text":"~/.claude/.../memory/feedback_publish_false_foundation_strategy.md"}]]}]

ADR-025

Per-crate semver via release-plz (publishable crates only)

accepted · 2026-04-16 · L5 · cites 3

ADR-025: Per-crate semver + release-plz #

Context #

Workspace currently uses single version = "0.80.0" shared across all crates. With the foundation publish = false strategy (ADR-022), only nika (binary) and future nika-sdk reach crates.io. Their semver should evolve independently of internal foundation crate refactors.

Decision #

Two-tier semver policy:

Foundation crates (`publish = false`) — keep workspace-shared version version.workspace = true. Not published, semver irrelevant for ecosystem.
Publishable crates (`nika`, future `nika-sdk`) — independent semver via release-plz GitHub workflow. Each crate has its own version field, bumped semantically based on conventional-commit messages affecting that crate.

Initial publishable versions:

[email protected] — binary republish from legacy v0.47.1 (yank old, fresh start with diamond architecture once binary is wired)
[email protected] — first publication when v0.90 reaches stable surface

release-plz workflow runs on push-to-main, opens a PR with version bumps

CHANGELOG entries derived from commits, auto-publishes on PR merge.

Consequences #

✅ nika binary version reflects user-facing API stability, not internal refactor churn
✅ nika-sdk ships independently — bug-fix release doesn't bump main binary
✅ release-plz handles changelog generation + GitHub releases automatically
❌ One-time workflow setup (~2h, one commit)
⚠️ Conventional commit discipline becomes load-bearing (already mostly true via commitlint hook)

Crates.io legacy cleanup (handled in Phase B.0) #

text

1cargo yank [email protected]      # diamond renames it; legacy abandoned2cargo yank [email protected]     # legacy3cargo yank [email protected]    # legacy, rebranded as nika4# [email protected] stays; republish at v0.80+ when binary is wired

Reference #

release-plz docs: https://release-plz.ieni.dev/
ADR-022 (publish=false strategy)
~/.claude/.../memory/feedback_publish_false_foundation_strategy.md

read at v0.107.0 · the decision record ships with the engine

Every decision, with its status This one in the repo