API Stability Policy
This document defines what ruprizzle commits to under semantic versioning, from the
first stable release onward, and how that commitment is enforced. It exists so that
"we follow semver" is a checkable claim rather than a habit — see W6-02 in
ProjectPlan/v1/PathToStableV1.md.
1.5.1 — the first published stable release — shipped on 2026-09-13, so this policy
is now in force — it is no longer a description of a target. Everything below applies
to the published 1.x line. The v1.0.0 and v1.0.1 tags were cut earlier but their
publish runs never uploaded, so they carry no stability commitment of their own. The
0.x prereleases are superseded; see docs/MigrationGuideToV1.md for what changed
getting here from 0.1.1-beta.1.
Two things about how the stable line was reached are recorded rather than glossed: the
release-candidate feedback window was waived (see the waiver at the end of this
document), and the 1.x line is
pinned to sqlx 0.8 because ruprizzle re-exports it (see "Public dependencies").
What is covered by semver
The following are covered — a breaking change to any of them requires a major version bump:
ruprizzle(the runtime crate). Its public items as enumerated bycargo public-api: the query builder (SelectQuery,InsertQuery,UpdateQuery,DeleteQuery,InsertManyQuery, and their terminal methods),PoolandPoolConfig,Transaction,Errorand its variants' matchablekind()strings,Related<T>, theraw!macro re-export, and thepreludemodule.ruprizzle-migrate. The diff engine's public API (diff, change-class types), the migration runner (MigrationRunner,MigrationMeta), and squashing/rename-detection entry points thatruprizzle-cliand third-party tooling can call directly.ruprizzle-core,ruprizzle-dialect,ruprizzle-parser,ruprizzle-codegen. These are published, and their public surfaces are semver-covered like any other published crate, but they are lower-level thanruprizzleandruprizzle-migrateand are expected to see fewer direct downstream consumers.ruprizzle-core::ir's IR types are exposed with wide field visibility by design (ADR-007) rather than through an accessor API — this means the IR's shape is part of the semver surface, not just its module paths. Exception: W2-02's join result typing is explicitly called out inPathToStableV1.mdas provisional and reviewed by W6-01; if it needs to change shape before1.0.0, that change is not held to the RC feedback window described below.- Generated client code's public shape. The entity structs, column tokens, and query-builder
entry points that
ruprizzle generateemits from a.ruprizzleschema are part of the user contract: a schema that generates and compiles today must keep generating and compiling after a patch or minor bump. The internal implementation of the generated code (exact token names for private helpers, module layout inside the generated file, exactTokenStreamshape beforeprettypleaseformatting) is not covered — only the parts a user's own code references (entity field names/types, relation accessors, query builder methods you call from application code). - The
ruprizzle-clibinary's command surface (subcommands, flags, exit codes) is treated as semver-covered even though it has no library API: a script that callsruprizzle migrate deploytoday should still work after a minor bump.
What is explicitly NOT covered
These may change in any release, including a patch release, without a major version bump:
ruprizzle-testkit. Shipspublish = falseand its own README says "not published." It exists to give the workspace's own test suites a dual-database harness and is not intended for external use.xtask. Repository automation only (publish = false), not a crate anyone depends on.- Anything under a crate's
benches/directory, including theend_to_endbenchmark harness incrates/runtime/benches, and any type that exists solely to support it. - Generated code's internal helpers — private (non-
pub, orpubonly within the generated crate) items in generated output. See "generated client code's public shape" above for the boundary. - Anything marked
#[doc(hidden)]. Used for items that must bepubfor a macro or trait bound to work but are not part of the intended API surface. - Anything under an
unstableCargo feature flag, should one be introduced. No crate currently defines one; if a genuinely experimental capability needs to ship ahead of a stability commitment, it goes behind--features unstable, is documented as such in its rustdoc, and is exempt from the semver guarantee and fromcargo-semver-checksgating described below. - Error message text.
Error'sDisplayoutput andmiettediagnostic rendering may be reworded at any time; onlyError's variant shapes andkind()strings are semver-covered, because those are what calling code is expected to match on. - Dependency versions. Bumping a dependency (e.g.
sqlx,chrono) is not itself a breaking change to ruprizzle's own API, even though it can occasionally change what types are re-exported through trait bounds; those re-export changes are evaluated case by case against the categories above.
MSRV policy
Current MSRV: Rust 1.85 (rust-version = "1.85" in the workspace Cargo.toml,
inherited by every crate via rust-version.workspace = true, and checked in CI's msrv job
in .github/workflows/ci.yml, which reads the same field and runs cargo test --workspace
against it).
Policy for the published 1.x line:
- MSRV may be bumped in a minor release (e.g.
1.6.0), not a patch release. - An MSRV bump is called out explicitly in
CHANGELOG.mdunder its own heading, not buried in "Changed." - MSRV is bumped no more than roughly once every six months, and only to pick up a toolchain feature actually used by the codebase or a dependency's own MSRV bump that cannot reasonably be pinned around.
- The CI
msrvjob is the enforcement mechanism: it fails the build if any crate's code requires a newer toolchain than the declaredrust-version.
Public dependencies
Some of ruprizzle's dependencies are part of its own public API, because their types appear in
signatures users write. crates/runtime/src/lib.rs re-exports them so that a caller's version
and ours are guaranteed to be the same crate:
| Crate | Version on the 1.0 line | Where it surfaces |
|---|---|---|
sqlx | 0.8 | pub use sqlx;, Pool, Tx, Executor, every FromRow impl |
serde | 1 | pub use serde;, derives on generated entities |
serde_json | 1 | pub use serde_json;, the Json column type |
rusqlite | 0.32 | pub use ::rusqlite::{Row, types} behind sqlite-rusqlite |
A major bump of any crate in this table is a breaking change to ruprizzle and requires a
major version bump of ruprizzle itself. This is not a policy choice — it is a consequence
of the type system. If your application depends on sqlx 0.9 and ruprizzle 1.x, Cargo will
link two incompatible copies of sqlx and your PgPool will not be our PgPool.
Two consequences worth stating plainly, because they will surprise someone:
- The 1.0 line is pinned to
sqlx 0.8.sqlx 0.9.0shipped 2026-05-06 and was considered for1.0.0. It was deferred: it makes allquery*()functions takeimpl SqlSafeStr(133 call sites here build SQL dynamically), makesSqliteValue!SyncandSqliteValueRef!Sendon the decode path, removes lifetimes fromAnyArgumentsand theArgumentstrait, changes MySQL text/blob conversion behaviour, and raises the toolchain floor to 1.86. That is a2.0.0-sized change, and doing it hastily on the way out the door was judged worse than doing it deliberately. SeeProjectPlan/v1/V1StableRelease.mdD2 for the full reasoning, andProjectPlan/v2/V2FeaturesPlan.mdfor where it is tracked. - Non-public dependencies carry no such promise.
pest,syn,quote,prettyplease,miette,tracing,clap,notify,criterion, andmetricsare implementation details. They may be bumped across major versions in a minor release of ruprizzle, because none of their types reach a user's code.
Deprecation process
- An item slated for removal is marked
#[deprecated(since = "X.Y.Z", note = "...")]with a note that says what to use instead (or that there is no replacement and why). - Deprecated items remain functional — not just present but working — for at least one
full minor version after the deprecation is introduced, and are only removed in the next
major version after that. Concretely: an item deprecated in
1.2.0stays working through at least1.3.x, and can only be removed starting at2.0.0. - Every deprecation and every removal of a previously-deprecated item is recorded in
CHANGELOG.md, under "Deprecated" and "Removed" respectively (Keep a Changelog's standard headings), with the same before/after treatmentdocs/MigrationGuideToV1.mduses for the 0.x-to-1.0 transition. cargo-semver-checks(see below) does not currently model deprecation windows — it flags true breaking changes (removed items, changed signatures). It does not stop a deprecated item's removal at a major version; that discipline is a matter of the PR review process documented inCONTRIBUTING.md, not a mechanical gate.
Enforcement: cargo-semver-checks in CI
Mechanical enforcement of everything above lives in the semver-checks CI job (see
.github/workflows/ci.yml), added under W6-03. It runs cargo-semver-checks against every
published, semver-covered crate on every pull request, comparing the working tree's public API
to the latest version published on crates.io. A detected breaking change without a
corresponding major (pre-1.0: minor) version bump fails the job.
cargo-semver-checks does not (yet) understand the "generated code" or "CLI command surface"
carve-outs above by construction — it checks Rust-level API surface. Breaking changes confined
to those categories are still expected to be called out by hand in CHANGELOG.md and reviewed
in PR, same as any other user-facing change.
Release candidates (W6-04)
1.0.0 is not cut directly from a 0.x release. Before it, the project publishes
1.0.0-rc.1 (and, if feedback requires changes, 1.0.0-rc.2, etc.) as an ordinary crates.io
prerelease.
- What
1.0.0-rc.1means: the public API is believed frozen — everything in "What is covered by semver" above is intended to be the final1.0.0shape — but the release is not yet a stability commitment. A breaking change discovered during the RC window is still fixed by breaking the API again in1.0.0-rc.2, not by shipping the mistake into1.0.0and deprecating it. - Feedback window: at least two weeks of real-world use between publishing
1.0.0-rc.1and cutting1.0.0, and longer if substantive feedback arrives near the end of the window (each round of feedback that produces an API change restarts a shorter, focused window rather than the full two weeks). The plan's rationale (PathToStableV1.md) is explicit that the current download count (43, across four0.xprereleases) is not enough exposure to freeze an API on without external eyes on the RC specifically. - What reviewers should focus on: exactly the semver-covered surface above — does the
query builder read naturally from application code, does
Errormatching work the way itskind()strings imply, does a generated schema from0.1.1-beta.1still compile after followingdocs/MigrationGuideToV1.md. Feedback on the generated-code internals orxtaskis out of scope for the RC gate, since those are not semver-covered. - What this repository does not do during an RC window: merge new features into the RC
branch. Only fixes to bugs found during the window and, if needed, API corrections land;
anything else waits for
1.1.0.
This section documents the process; it does not itself cut a release. 1.0.0-rc.1 was
published to crates.io on 2026-08-21 from tag v1.0.0-rc.1. The stable release this
RC fed into was eventually published as 1.5.1 on 2026-09-13 — the v1.0.0 and
v1.0.1 tags in between never produced a package. See the W6-04/W6-05 status
note in ProjectPlan/v1/PathToStableV1.md.
Waiver: the 1.0.0-rc.1 feedback window (2026-08-21)
The two-week window described above was waived for the 1.0 stable line. The v1.0.0
tag was cut the same day 1.0.0-rc.1 was published, rather than on or after 2026-09-04
(its publish run then failed before uploading; the first published stable became 1.5.1).
This is recorded here rather
than left implicit, because a policy the project did not follow is worse than a policy it
amended on purpose. The decision, its rationale, and the alternative considered are written up
as decision D1 in ProjectPlan/v1/V1StableRelease.md; it follows the same pattern as the
W4-02 soak waiver in docs/SoakReport.md.
- Why. The window's purpose is external eyes on a frozen API. Across seven
0.xprereleases the project has 43 total downloads and no known external consumer, so the two weeks would have bought calendar time and no feedback. The related definition-of-done item — "at least one external project reporting a successful upgrade" — is waived for the same reason: there is no such project to report one. - What stands in its place. The full gate matrix in
V1StableRelease.md§6, run against the tagged commit:fmt,clippy -D warningsacross the feature matrix, the workspace test suite against a live PostgreSQL,cargo doc --all-featureswith-D warnings,cargo deny check,cargo xtask harden, andcargo xtask release-check --tag. Pluscargo-semver-checks, which continues to compare every published crate's API against the last release on crates.io — from the first published stable (1.5.1) onward that comparison is the semver gate. - What this waiver does not do. It does not repeal the policy. A future
2.0.0-rc.1, or any RC published once real downstream users exist, gets the full window. It also does not weaken the semver commitment: if an API defect surfaces in the field, the answer is the next minor for an addition and2.0.0for a break, under the deprecation process above — not a retroactive redefinition of what1.0.0promised.
One-time exception: 1.0.0-rc.1 → 1.5.1
1.5.1 is the first stable release after 1.0.0-rc.1. Its public API differs from the RC
in ways cargo-semver-checks classifies as major: new variants on exhaustive enums, new
fields on constructible structs, three diagnostic enums made #[non_exhaustive], and four
internal modules made #[doc(hidden)]. As the release-candidates section above allows,
these are accepted as RC → stable changes rather than forcing 2.0.0. Two conditions
apply:
- Every item is documented with a fix in Upgrading from 1.0.0-rc.1, together with what was verified to stay compatible: clients generated by rc.1, migration snapshots and query manifests.
- The exception covered this one upgrade only. With
1.5.1published, the CIsemverjob's temporaryrelease-type: majorhas been removed and thepublic-apibaseline is1.5.1with--deny=all; every rule on this page now applies unchanged.