ADR-0035: Publish the crates to crates.io at the product version¶
- Status: Proposed
- Date: 2026-11-04
- Issues: none yet (requested by the maintainer; unblocks
buchochelliq-labs/open-data-suite-ontologyon crates.io) - Deciders: @n1ckyb
Context¶
ADR-0019 says every crate has publish = false and nothing is on crates.io: only the
ods binary reaches users. Two things have changed:
- A downstream Rust consumer. open-data-suite-ontology (onto) reads ODS's ERD
output with ods-erd's types (Erd, Entity, Relationship, Key, Basis), so
it doesn't re-derive ODS's model. It depends on ods-erd from git, which crates.io
rejects, so onto can't be published there either.
- Plugins. ADR-0031 lets third parties write plugins against ods-sdk's
contracts, and ADR-0006 gives each contract a fake and a conformance suite. Without
published crates, a plugin author can only depend on ODS from git.
ADR-0019 rejected publishing (its Option B) for independent per-crate versions: a compatibility matrix and release tooling for every crate. Publishing every crate at the one product version avoids both.
Nothing else blocks publishing:
- every crate name is free on crates.io;
- no crate embeds files from outside its directory;
- the one git dependency, rs-rich and rs-rich-ext (for ods-cli's rendering), is
on crates.io with the features ODS uses (rs-rich 0.0.14, rs-rich-ext 0.0.21 with
sql and markdown).
Options considered¶
Option A — Publish every crate at the product version (chosen)¶
- Pros:
- One rule, and ADR-0019's single version kept:
ods-*X.Y.Z are the crates ofodsX.Y.Z, published by thevX.Y.Ztag. No compatibility matrix. cargo install ods-cliinstallsods, alongside pip, Homebrew and Chocolatey.- Consumers (
onto) and plugin authors (ods-sdk,ods-provider-fake) depend on released code. - Cons:
- A crate's version moves with the product even when it didn't change.
- Every internal path dependency carries the version, so a release bumps it in one more place. Cargo refuses a mismatch, so it can't be forgotten silently.
- Names and published versions are permanent: a crate can be yanked, never removed.
Option B — Publish only ods-erd¶
ods-erd is a leaf crate (serde only).
- Pros:
- The smallest change that unblocks onto.
- Cons:
- It answers one consumer, not the plugin story. The next consumer, or the first
plugin author, needs this decision again.
Option C — Independent SemVer per crate¶
- Cons:
- ADR-0019's Option B. Still premature before SDK 1.0.
Decision¶
Every workspace crate is published to crates.io at the product version by each vX.Y.Z
release.
- workspace.package.publish = true. Internal dependencies in
[workspace.dependencies] carry version equal to workspace.package.version, and
the release PR bumps both.
- No crate may depend on git. Every dependency must be on crates.io, or be another
workspace crate.
- .github/workflows/release.yml publishes them after the GitHub release, from the
crates-io environment, in one cargo publish of every crate whose version
crates.io doesn't have yet. Cargo orders them by dependency. Trusted Publishing is
used once each crate exists; a crate's first version uses an owner's token.
- CI packages every crate on each PR (cargo publish --workspace --dry-run).
- Interfaces keep ADR-0019's own versions (SDK, contracts, JSON schema, store schema).
The crate version is the product version.
This amends ADR-0019's "nothing is on crates.io". It keeps ADR-0019's single version.
Consequences¶
- Positive:
ontoand plugin authors depend on released crates.cargo install ods-cliis one more way to install.- Packaging problems show on PRs, not at release.
- Negative / trade-offs:
- Every public item of every crate is now visible API. ADR-0019's rules apply to the product as a whole: before 1.0 a minor may break, and breaks are listed under Breaking. Crate APIs get no guarantee beyond that.
- One-time setup by a crates.io owner (a first-version token, then Trusted Publishers). A release that adds a new crate needs the token again.
- The release takes a few minutes longer.
- Follow-up issues:
- With SDK 1.0, decide whether
ods-sdkgets its own version (ADR-0019's superseding ADR).
References¶
- ADR-0019 (release and versioning), ADR-0001 (layering), ADR-0006 and ADR-0031 (contracts and plugins), ADR-0003 (rs-rich).
- crates.io Trusted Publishing: https://crates.io/docs/trusted-publishing