claude@clouddev1
e9606b5f6d
ci / gate (push) Successful in 3m14s
Distribution prep on the road to public availability (plan steps 2–3a). - Cargo.toml: publish-ready (drop publish=false; homepage/keywords/ categories/exclude) + [package.metadata.binstall] with per-target overrides (linux-gnu->musl, windows-msvc->gnu/gnullvm). dry-run clean. - scripts/install.ps1: Windows `irm | iex` one-liner — written but untested here (no PowerShell; validate on Windows). README Windows block. - README.md (new); LICENSE-MIT + LICENSE-APACHE (dual, (c) Lazy Evaluation Ltd); CONTRIBUTING.md (inbound=outbound dual-license note). - ADR-0055 Amendment 1 (install.ps1), ADR-0056 (crates.io/binstall), README index + plan updates. The actual `cargo publish` remains a gated maintainer step (token, irreversible) at a new tagged release; real cargo-binstall validation pending.
89 lines
4.3 KiB
Markdown
89 lines
4.3 KiB
Markdown
# 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).
|