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).

## Amendment 1 — 2026-06-18: published live + a manual `publish` workflow

**`rdbms-playground 0.2.0` is published to crates.io** (`cargo install` and
`cargo binstall rdbms-playground` both verified working by the user). The
"unverified binstall" caveat is resolved — the per-target overrides
resolve correctly against the `v0.2.0` release assets.

**How publishing is wired:** a new **manual `workflow_dispatch` workflow**
(`.gitea/workflows/publish.yaml`), mirroring `release-macos.yaml`, takes a
`tag` input and runs `cargo publish` (token via the
`CARGO_REGISTRY_TOKEN` Gitea Actions secret — a crate-scoped,
publish-update token). **Not** automated on the tag, by decision: the
publish is irreversible (yank-only), keeping the registry token off every
tag push; the release is split (Linux/Windows on the tag, macOS
dispatched), so a human is the natural "all assets are up — go" gate; and
crates.io has no Gitea-Actions trusted-publishing path today, so a stored
token on the self-hosted runner would be the only automated option.
Each registry is its **own idempotent job** (no inter-job `needs`) — the
crates.io job skips cleanly if the version is already published (crates.io
API pre-check + `cargo publish` as the backstop) — so future
Scoop/Homebrew/winget jobs can be added alongside without breaking one
another or re-runs. The first such job's `tag`-vs-`Cargo.toml` guard
mirrors `release.yaml`.