.nornir/release-for-idiots.md · nordisk/dwarves

release for idiots — the three verbs

You have a multi-repo Rust workspace. You changed something. Can you release it, and in what order, without breaking the cascade on real crates.io? nornir has holger baked in (a fake crates.io called /sparring) so you can REHEARSE the whole thing locally first. Three verbs, advise → rehearse → ship.

# ── stand in your workspace (or pass --server) ───────────────────────
cd workspace_nordisk         # or wherever your nornir-workspace.toml lives

# 1. ADVISE (read-only, mutates nothing) — what's off, in what order?
nornir release doctor
#    → dirty trees · version skew across repos · publish order · blast radius.
#      Two hint flavours: `💡 bump → X` is a free edit; `⛔ blocked → X` means a
#      TRANSITIVE dep pins the old major (a manifest bump won't take — `cargo tree
#      -i X` to find it). `--forbid arrow=56` bans a version.

# 1b. Is the crate on the current Rust standard? (edition 2024 / MSRV / resolver-3)
nornir release gate edition <repo>   # static + a 2024-compat lint pass

# 2. REHEARSE (dry-run first, then for real) — does the cascade resolve?
nornir release stage                 # PLAN only: prints publish order + verify set
nornir release stage --execute       # boots embedded /sparring → cargo publish each
#      repo into it in order → cargo build each dependent FROM /sparring. holger is
#      torn down after; the registry is throwaway. Nothing hits real crates.io.

# one-shot: advise THEN rehearse in a single command
nornir release doctor --rehearse

# 3. SHIP — replay the same order against real crates.io (once rehearsal is green)
nornir release publish

What "green" looks like

$ nornir release stage
  Publish order (dependencies first):
    1. cargo publish znippy → /sparring
       verify (build from /sparring): holger, nornir
    2. cargo publish holger → /sparring
    3. cargo publish nornir → /sparring
  → green plan; run with --execute to publish into /sparring, then promote.

A dependency cycle prints ⚠ NOT executable and blocks --execute — fix the cycle first. (publish = false crates and optional deps are ignored, so a dev-only tooling link between two repos isn't a false cycle.) doctor also suggests the cut: per cycle it names the cheapest edge to break (the one on the fewest crates) and how — "extract into a shared leaf crate, or make it optional".

Don't want the shell? Drive it in the viz

nornir viz → the 🧬 nornir tab paints the publish graph with every problem overlaid on the node (⛔ held · ✗ edition-fail · ▼ behind · 🟡 dirty), each cycle as a dashed ✂ cut edge. The 🚀 Release button opens the 🧙 wizard — a gated Advise → Fix → Rehearse → Promote walk; you can't skip a red step without an override, and Promote makes you type PROMOTE. Same engine as the CLI, just clicked instead of typed.

The other holger verb — the cache

Same embedded holger also serves a crates.io mirror for fast/offline builds:

nornir cache up        # /cache (mirror) + /sparring (rehearsal), in-process.
                       # Prints the cargo snippet to point your builds at it.

Gotchas

--execute mutates: it cuts an ephemeral release branch and runs real cargo publish (into the local /sparring, not crates.io). doctor without --rehearse never mutates.
/sparring mirrors crates.io upstream — you publish your OWN crates into it; names that already exist on real crates.io collide. (Your workspace crates are unique, so this only bites toy fixtures.)
Lean build: cargo install nornir --no-default-features … drops embedded holger; then --execute/cache up spawn a holger-server subprocess instead (pass --holger-bin).

Full reference + the nordisk go-live runbook: release-rehearsal.md.

If you are an agent, not a human

Same cascade, five MCP tools on dwarves-server mcp. Four of them cannot break anything — they only look:

release_plan        → the publish waves and the exact `cargo publish` argv (offline)
release_publishable → what ships, and at what version
release_drift       → LIVE: what is safe to skip, and what DRIFTED (the dangerous one)
release_gates       → LIVE: every blocker, each with the fix written next to it

Start at release_plan (offline, sub-second), then release_drift, then release_gates. Fix what release_gates tells you to fix, then run it again — the count going down is the only progress report you should trust.

drifted is the word to be afraid of. It means the crate is already on crates.io at that exact version number, and the source in front of you is not what is up there. crates.io bytes are immutable, so you cannot fix it by republishing: you bump the version. And when you bump a crate, anything that names it by an exact version needs raising too — which drifts that crate, which needs its own bump. Follow the chain until release_drift stops changing.

You cannot publish. release_publish is a dry run unless the server was armed by a human with DWARVES_MCP_ALLOW_PUBLISH=1 and you send the phrase PUBLISH-TO-CRATES-IO verbatim. This is not a formality. Publishing is the one thing here that cannot be undone, and it is somebody's namespace. When it refuses, it hands you the command a human would run — give them that, and stop.

If tools/list shows only three tools (funnel_*, autonom_kick), the server was built without --features release. That is a build problem, not a permissions problem, and no amount of retrying will change it.