rdbms-playground/docs/adr/0056-crates-io-and-cargo-binstall.md

ADR-0056: crates.io publish-readiness + cargo binstall metadata (D3)

Status

Accepted — prepared 2026-06-17 (plan: docs/plans/20260616-public-availability.md, step 3a). The crate is made ready to publish and carries cargo-binstall metadata. The actual cargo publish is a gated maintainer step (see Ordering). First D3 package-manager mechanism; builds on ADR-0054 (versioned releases), ADR-0055 (installer), ADR-ci-003 (release assets). Tracked by plan + ADR (no Gitea issue — user decision).

Context

cargo binstall rdbms-playground (and cargo install) need the crate on crates.io (user decision, 2026-06-17). The manifest had publish = false, a readme = "README.md" pointing at a missing file, and no keywords/categories. Our release assets are bare binaries (not archives) named rdbms-playground-v<version>-<target> (.exe on Windows) with .sha256 sidecars (ADR-ci-003); critically the release target triples differ from users' host triples — we ship the static *-linux-musl build (hosts are *-linux-gnu) and *-windows-gnu/-gnullvm (hosts are *-msvc); only macOS matches.

Decision

Publish-readiness (this change):

• Drop publish = false; add homepage = "https://relplay.org", keywords, categories = ["command-line-utilities", "database"], and an exclude (/website, /docs, /.gitea, /.codegraph) so the published crate is code-only (585 files/8.3 MiB → 353/913 KiB compressed).
• Author README.md (the readme target + crates.io front page; engine-neutral and "simple/advanced mode" wording per ADR-0002 / the website copy rules), with install instructions (curl|sh, binstall, source, prebuilt).
• Add LICENSE-MIT and LICENSE-APACHE (the latter the verbatim canonical text, added by the maintainer; both © Lazy Evaluation Ltd — the publication entity), and a CONTRIBUTING.md stating the "inbound = outbound" dual-license arrangement (so Apache-2.0 §5 makes the §3 patent grant explicit on the self-hosted forge). Dual license kept (not MIT-only) — user decision after reviewing the patent-grant rationale.

cargo binstall metadata ([package.metadata.binstall], syntax verified against cargo-binstall SUPPORT.md):

• pkg-fmt = "bin" (bare binary), bin-dir = "{ bin }{ binary-ext }", and a base pkg-url using v{ version } (the { version } placeholder excludes the leading v).
• Per-target overrides mapping the common host triples to the asset we actually publish: x86_64/aarch64-unknown-linux-gnu → the -musl asset; x86_64/aarch64-pc-windows-msvc → the -gnu/-gnullvm .exe. macOS needs no override (host triple == asset triple). The docs do not promise automatic musl/gnu or msvc/gnu fallback, hence explicit overrides.

Ordering / gating (important):

• cargo publish is irreversible (needs the crates.io token; a version can't be un-published, only yanked) — a deliberate maintainer step, not done here.
• binstall's pkg-url resolves to a tagged release's assets, so publish at a new tagged version whose release already exists, and publish after that release is built. Do not publish 0.1.0 — it would diverge from the already-released 0.1.0 binaries (which predate --version, ADR-0054). The clean path: bump → tag → release builds → cargo publish.

Verification

• cargo publish --dry-run --allow-dirty packages + verify-builds cleanly (353 files, 913 KiB compressed; no metadata errors).
• cargo metadata confirms the binstall block + all four overrides parse.
• Unverified: an actual cargo binstall run — cargo-binstall isn't a dependency and nothing is on crates.io yet. Validate at the first publish + matching release (especially the windows-msvc→gnu and linux-gnu→musl overrides).

Consequences

• The crate can be published at the next tagged release with cargo publish (+ the token); cargo install rdbms-playground and cargo binstall rdbms-playground then work.
• Remaining D3: Scoop, Homebrew (lazyeval tap), winget (komac/manual) — each a manifest + a per-release bump, tracked in the plan.
• Remaining follow-up: run the real cargo binstall validation at the first publish + matching release (the license files, © holder, and CONTRIBUTING are now in place).