API design: SemVer, compatibility checks, and public API shape
Unresolved research. This topic is evidence that research-topic gathered, waiting on resolve-research. It isn't an opinion, and it can cite unvetted material. Follow the opinions instead.
Design a library's public API so that you can add to it in a minor release, and check every release for accidental breakage before you publish:
- Treat the Cargo Book's SemVer chapter as the rule book. Removing or renaming a public item, adding a public field to a struct with no private ones, adding a variant to an exhaustive enum, adding a non-defaulted trait item, and removing a Cargo feature are all major changes.
- Mark a public struct or enum
#[non_exhaustive]when you introduce it, unless the set is closed. Adding the attribute later to a type with no private fields is itself a major change. - Seal a public trait that downstream code doesn't need to implement, so you can add items to it later.
- Prefer concrete types, newtypes, and enums to
booland to generics in public signatures, and add#[must_use]where ignoring the return value is a bug. - Document every public item, with
# Errorson a function that returnsResult,# Panicson one that can panic, and# Safetyon anunsafe fn, and turn on the lints that enforce it. - Treat a
rust-versionbump as a minor change, under a written MSRV policy of the latest stable release and the two before it. - Check every release for SemVer breakage before
cargo publish.cargo-semver-checksis the candidate tool, and the Rust standard library now runs it. Recommending it is still pending, because the case for adopting it rests on its author alone.
Everything recommended here is stable in Rust 1.99.1 (released 2026-10-15). The two features that would build sealing and public-dependency tracking into the language and Cargo, impl restrictions and public dependencies, are unstable on nightly as of 2026-10-19. For their status, see Coming next.
No opinion file covers this. opinions/rust.md covers argument-position impl Trait and pushing conditions to the caller, and says "For public API shape, see api-design.md, which isn't written yet." This topic is the api-design.md row in PLAN.md: Phase 6.
Neither of the plan's two expected sources supports this topic alone. api-guidelines is on the watch list as dormant, so it can't support a claim here. predrag is citable, but its roster note says never to cite it alone on adopting cargo-semver-checks. rust-docs supports the SemVer rules instead, and corrode, burntsushi, and matklad support the API shape.
What counts as a breaking change
The Cargo Book classes each change as major, minor, or possibly breaking (The Cargo Book: SemVer Compatibility). These are the less obvious rows, with the chapter's anchor for each:
| Change | Class | Anchor |
|---|---|---|
| Add a public field when no private field exists | Major | struct-add-public-field-when-no-private |
| Add a private field when all current fields are public | Major | struct-add-private-field-when-public |
| Add or remove a private field when one already exists | Minor | struct-private-fields-with-private |
Add an enum variant without #[non_exhaustive] |
Major | enum-variant-new |
Add #[non_exhaustive] to an existing type with no private fields |
Major | attr-adding-non-exhaustive |
| Add a non-defaulted trait item | Major | trait-new-item-no-default |
| Add a defaulted trait item | Possibly breaking | trait-new-default-item |
| Add any inherent item | Possibly breaking | impl-item-new |
Capture more generic parameters in a return-position impl Trait |
Major | generic-rpit-capture |
| Change the minimum Rust version | Possibly breaking | env-new-rust |
| Remove a Cargo feature | Major | cargo-feature-remove |
| Remove an optional dependency | Possibly breaking | cargo-remove-opt-dep |
For a 0.y.z release, a change in y counts as major and a change in z as minor. Every 0.0.z release is major.
Two of the chapter's mitigations are rules to apply when a type or trait is first published: "Mark structs, enums, and enum variants as #[non_exhaustive] when first introducing them, rather than adding #[non_exhaustive] later on", and "When introducing the trait, use the sealed trait technique to prevent users outside of the crate from implementing the trait."
A private field can change a public type's auto traits. The chapter doesn't name Send or Sync. predrag shows the case: changing a private field from String to Rc<str> makes the public struct neither Send nor Sync, which is a major change (Predrag Gruevski: Toward fearless cargo update, 2022-08-25). The Rustonomicon's rule that a type made only of Send or Sync types is itself Send or Sync is the mechanism (The Rustonomicon: Send and Sync). Removing an auto-trait impl was the fourth most common violation in predrag's study, which Checking SemVer before publishing describes.
Adding a public item is technically breaking, and still minor. A new item can collide with a downstream glob import. RFC 1105 says "all major changes are breaking, but not all breaking changes are major", and a minor release can contain breakage the user can fix locally (Predrag Gruevski: Some Rust breaking changes don't require a major version, 2023-01-26, quoting RFC 1105: API evolution).
MSRV
For a published library, support the latest stable release and the two before it, set package.rust-version to the oldest of the three, and treat a bump as minor. The Cargo Book's rust-version page says changing it "is assumed to be a minor incompatibility". It recommends that you "Choose a policy for what Rust versions to support and when that is changed", and says "The simplest policy to support is to always use the latest Rust version". Its example policies include N-2, "latest version with a 2 release grace window for updating" (The Cargo Book: Rust version). The SemVer chapter agrees: "It is generally recommended to treat this as a minor change".
The policy is N-2. On Rust 1.99, that's rust-version = "1.97". The page gives N-2 as an example and doesn't choose between its examples, so the choice is the owner's, made on 2026-11-12, and no source makes it. Always using the latest release would stop a user one release behind from taking an update.
The page expects each supported version to be "verified on its supported Rust versions, including automated testing", which belongs in ci.md.
Cargo features
Make features additive, and hide optional dependencies behind dep:. The Cargo Book says "enabling a feature should not disable functionality, and it should usually be safe to enable any combination of features". For no_std, use a std feature that enables std, not a no_std feature. Don't remove a feature, move public code behind a feature, or remove a feature from another feature's list in a minor release (The Cargo Book: Features).
The dep: prefix removes the implicit feature an optional dependency would otherwise create. That keeps a dependency an internal detail. Adding the prefix to a published crate removes that feature, though: predrag shows that max_performance = ["dep:rayon"] "is quietly removing the rayon feature", which is a major change (Predrag Gruevski: Breakage! in the Cargo.toml, 2024-12-04).
Checking SemVer before publishing
cargo semver-checks is the candidate check, pending a second citable source. It compares the rustdoc JSON of the new version against the last published one, and fails on any violation it has a lint for. The latest release is 0.51.0, from 2026-10-03, with rust-version 1.93 (crates.io, checked 2026-11-12). The RustSec Advisory Database lists no advisory for the crate (checked 2026-11-12). That lookup covers the crate itself, not its dependencies.
The evidence that maintainers need a tool, not more care:
- Violations are common. Of 14,389 minor and patch releases of the 1,000 most-downloaded crates, 464 (3.22%) broke SemVer, and 172 crates (17.2%) did so at least once. That's a lower bound, from default features and the lints of 2023 (Predrag Gruevski: Semver violations are common, better tooling is the answer, 2023-09-07).
- The Rust standard library broke this way. Rust 1.94.1 removed new methods from
std::os::windows::fs::OpenOptionsExt, because "the trait itself is not sealed and so cannot be extended with non-default methods" (Rust Blog: Announcing Rust 1.94.1, 2026-03-26). - The standard library now runs
cargo-semver-checksin its CI, with unstable items treated as non-public, "exactly as if they were#[doc(hidden)]" (Predrag Gruevski: Protecting the Rust standard library from accidental breakage, 2026-08-15).
Its limits: It has 242 lints as of the end of 2025, but it doesn't type-check, so changing x: i64 to x: String goes unreported. It also can't yet analyse items re-exported from another crate reliably, which is its largest source of false positives (Predrag Gruevski: Exponential growth continued: cargo-semver-checks 2025 Year in Review, 2026-01-11). A clean run is necessary, not sufficient, so the rules above still apply in review.
The case for adopting it rests on predrag alone, which blocks the recommendation. Predrag Gruevski wrote the tool, and the roster forbids citing him alone on adopting it. The Cargo Book's SemVer chapter names no tool. The 1.94.1 post shows the failure, but doesn't name a remedy. The only other endorsement is unvetted, so it's kept in Watch-list and unvetted material and can't support the claim. The opinion can state the rules and the need from citable sources, and can name the tool only once a second citable source, or an official Rust document, recommends it.
Future-proofing the shape
#[non_exhaustive] and private fields
Mark an open set #[non_exhaustive], and leave a closed set exhaustive. corrode: "mark your enum as #[non_exhaustive] so you can add variants later", but "If the set of possibilities really is closed, exhaustive matching gives users a useful guarantee". For an open-ended set of codes, such as HTTP status, it recommends an opaque struct with associated constants. Its test before publishing: "am I willing to uphold this guarantee forever?" (Matthias Endler: Local Reasoning in Rust, 2026-10-02, updated 2026-10-31).
#[non_exhaustive] works only across crate boundaries, and blocks struct literals outside the crate, so callers go through your constructor (Matthias Endler: Patterns for Defensive Programming in Rust, 2025-11-08). A struct that already has a private field gets the same protection without the attribute (Cargo Book, above).
Clippy's exhaustive_structs and exhaustive_enums, both restriction lints, report a public type without the attribute. Both fired in the editor's probe on 1.99.1, 2026-11-12.
Sealed traits
Seal a public trait unless downstream code must implement it. Adding a required item to an unsealed trait is major, and adding a defaulted one is possibly breaking. predrag describes three techniques (Predrag Gruevski: A definitive guide to sealed traits in Rust, 2023-04-05):
- Supertrait-sealed: the trait requires a supertrait whose name isn't exported. Downstream code can call the methods, but can't implement the trait.
- Method-sealed: a required method takes an argument of a type downstream code can't name.
- Partially sealed: only some methods take the unnameable type, and they have default bodies. Downstream code can implement the trait, but it can't override those methods. It can't call them either, unless the crate exports a function that calls them on its behalf.
The usual form is the supertrait seal:
mod private {
pub trait Sealed {}
}
/// A shape this crate can measure.
pub trait Shape: private::Sealed {
/// The area, in square metres.
fn area(&self) -> f64;
}
/// A square.
#[derive(Debug, Clone, Copy)]
pub struct Square(pub f64);
impl private::Sealed for Square {}
impl Shape for Square {
fn area(&self) -> f64 {
self.0 * self.0
}
}
This passes CARGO_BUILD_WARNINGS=deny cargo check and CARGO_BUILD_WARNINGS=deny cargo clippy on 1.99.1, with no crate beyond std (editor's probe, 2026-11-12).
Two things unseal a trait silently (Predrag Gruevski: Is this trait sealed, or not sealed, 2024-09-03): a pub use that makes the private type nameable, and a blanket impl such as impl<T: Clone> Sealed for T. A method-sealed or partially sealed trait has a third gap: a public function that returns a value of the token type. Downstream code can then call the methods that take it, though it still can't implement the trait (Predrag Gruevski: A definitive guide to sealed traits in Rust, above).
Options structs and builders
For a function with many optional parameters, take an options struct with Default. corrode recommends it over a builder: "Instead of optional arguments, we deal with data". A builder is for "when construction requires validation or conversion", and "builders should not be the default. They can become their own tiny programming language" (Matthias Endler: We Have Named Arguments at Home, 2026-09-24). burntsushi's Jiff uses builders, such as ZonedDifference and ZonedRound, only for the parameters of since, until, and round, with From impls to keep the simple call short (Andrew Gallant: Jiff design).
A public options struct conflicts with #[non_exhaustive]. corrode's call form, Options { retry: true, ..Default::default() }, fails in another crate once the struct is #[non_exhaustive]: "Non-exhaustive structs and enum variants cannot be constructed using struct literal syntax, including functional update syntax" (Cargo Book, above). It fails with E0639 (editor's probe on 1.99.1, 2026-11-12). Without the attribute, every new field is a major change.
In a library, use builder lite: Options::default().with_retry(true), with with_ methods on the #[non_exhaustive] struct itself. matklad calls it "an incremental, zero-cost evolution from the new method" (Alex Kladov: Builder Lite, 2022-05-29). His examples are application code, so applying it to a library is the editor's reading, and unsupported until a citable source says it. The call compiles across crates and passes Clippy (editor's probe on 1.99.1, 2026-11-12).
Mutating a default, let mut options = Options::default(); options.retry = true;, also compiles across crates when the fields are public (same probe). The owner ruled it out on 2026-11-12: no roster source recommends it, and it needs a statement for each field.
Struct-update syntax still works inside your own crate, and in application code, where no downstream crate can break.
Where the roster disagrees
- Options struct or builder.
corrodeprefers the options struct,burntsushiuses builders for parameter sets, andmatkladoffers builder lite. They agree on more than they differ:corrodekeeps the builder for validation or conversion, which is Jiff's case. In a library,#[non_exhaustive]rules out struct-update syntax, and builder lite replaces it. ..Default::default().rust.mdalready records thatcorrodewarns against it in the 2025 defensive-programming post and recommends it in the 2026 named-arguments post. For a public type, the Cargo Book now decides: a#[non_exhaustive]struct can't use it from another crate, and one that isn't#[non_exhaustive]can't add a field in a minor release.
Signatures and types
corrode gives the most rules, from one 2026 post and one 2025 post (both above):
- Make the signature tell the story. Decide what an empty string and
Nonemean, and whether each is an error, when you design the API. - Keep
&on an argument the function doesn't consume, so the call site shows the value doesn't move. - Return
impl Traitto hide a complex concrete type. "impl Iterator<Item = &str>tells the caller what they can do with the result". Two parts of the hidden type stay in the API:- What it captures. Capturing more generic parameters is a major change (Cargo Book, above). In edition 2024, the type captures "all in-scope generic parameters, including generic type, const, and lifetime parameters", unless a
use<..>bound limits it (The Rust Reference: Impl trait).rust-docs. - Its auto traits. A hidden type that holds an
Rcfailed a caller'sSendbound withE0277(editor's probe on 1.99.1, 2026-11-12). RFC 1522 states the rule: "OIBITs likeSendandSyncwill leak through an abstract return type", so changing the function's body can be "a silent breaking change" (RFC 1522: Conservativeimpl Trait, a reference, read 2026-11-14). That's a reference fact about the language feature, so it needs no roster source. Changing the hidden type can break a caller, as changing a private field can.
- What it captures. Capturing more generic parameters is a major change (Cargo Book, above). In edition 2024, the type captures "all in-scope generic parameters, including generic type, const, and lifetime parameters", unless a
- Use a newtype with a validating constructor for a value with an invariant, and give it an explicit accessor such as
as_str(). ImplementDerefonly "when the wrapper transparently behaves like its target and dereferencing is cheap and unsurprising". - Take an enum instead of a
boolparameter. Clippy'sfn_params_excessive_bools(pedantic) reports four or more. - Add
#[must_use]to guard types and to results the caller has to check. Clippy'smust_use_candidateandreturn_self_not_must_use(both pedantic) suggest where. - Prefer
BorrowedFdandOwnedFdtoRawFd, and wrap an unsafe API in a type that owns the resource.
Prefer a concrete type to a generic parameter. burntsushi made Jiff's Zoned concrete instead of generic over a time-zone trait, because "being able to just write Zoned as a concrete type without any generics is a huge win for comprehensibility". He made TimeZone closed for the same reason (Jiff design, above). rust.md already covers argument-position impl Trait, so the opinion links there instead of repeating it.
Re-export to shape the public path. The Book says to use pub use to "make a public structure that's different from your private structure", and to re-export a dependency's definitions that your API exposes (The Rust Programming Language: Publishing a Crate to Crates.io).
Documentation
Document every public item, and give it the sections the Book names. The Book lists # Panics, # Errors for a function returning Result, and # Safety for an unsafe function (Book, above). The rustdoc book recommends a one-sentence summary, a longer explanation, and "at least one code example that users can copy/paste to try it", and says "If an item is public then it should be documented" (The rustdoc book: How to write documentation).
Document the crate's features at the top of lib.rs, and leave out any optional dependency that users shouldn't enable directly (Cargo Book: Features, above).
Lints that enforce it
Each lint fired in the editor's probe on 1.99.1, 2026-11-12, and the level or group is the one the compiler reported:
| Lint | Level or group | Reports |
|---|---|---|
missing_docs |
rustc, allow | A public item, or the crate, without documentation |
missing_debug_implementations |
rustc, allow | A public type without Debug |
unreachable_pub |
rustc, allow | A pub item nobody outside the crate can reach |
clippy::missing_safety_doc |
style, warn | An unsafe fn without # Safety |
clippy::missing_errors_doc |
pedantic | A function returning Result without # Errors |
clippy::missing_panics_doc |
pedantic | A function that can panic without # Panics |
clippy::must_use_candidate |
pedantic | A pure function or method without #[must_use] |
clippy::return_self_not_must_use |
pedantic | A method returning Self without #[must_use] |
clippy::exhaustive_structs, clippy::exhaustive_enums |
restriction | A public type without #[non_exhaustive] |
The rustc lint descriptions are from The rustc book: Allowed-by-default lints. missing_panics_doc reports an unwrap or panic!, but not slice indexing.
Keep avoid-breaking-exported-api at its default, true. It suppresses 19 Clippy lints, among them wrong_self_convention, unnecessary_wraps, and trivially_copy_pass_by_ref, "whenever the suggested change would cause breakage for other crates" (Clippy: Lint configuration).
Whether to enable the exhaustive lints is a decision for the opinion. They suit a library that commits to #[non_exhaustive] by default, and fire on every closed set too, which then needs an #[expect] with a reason.
Coming next
Unstable on nightly as of 2026-10-19, not yet an opinion. The tracking issues are references, cited only to date this note.
| Feature | Status, 2026-10-19 |
|---|---|
impl restrictions, pub impl(crate) trait |
RFC 3323 is accepted, and the tracking issue is open (rust-lang/predrag notes that "Trait sealing isn't (yet!) a built-in concept" (2025-03-08) |
| Public and private dependencies | Open in both rustc and Cargo (rust-lang/exported_private_dependencies lint, which reports a private dependency's type in a public API, depends on it |
#[doc(cfg)] |
Open (rust-lang/ |
cargo-semver-checks in cargo publish |
An accepted 2026 Rust project goal, with no date. It waits on type-checking lints and cross-crate analysis (Rust Project Goals, unvetted, below) |
Watch-list and unvetted material
Kept apart from the roster findings above. None of it supported a claim. The "Coming next" row on cargo publish rests on the unvetted page alone.
- Watch-list
api-guidelines: the checklist has the items this topic covers, among them C-SEALED, C-STRUCT-PRIVATE, C-BUILDER, C-NEWTYPE, C-COMMON-TRAITS, and C-GOOD-ERR (Rust API Guidelines: Checklist). It agrees with the sealed-trait and private-field rules, which rest on the Cargo Book. Its C-COMMON-TRAITS item, to implementClone,PartialEq,Hash,Default, and the rest eagerly on public types, has no citable source here, so it can't go in the opinion yet. - Watch-list
ms-rust-guidelines,effective-rust, andjon-gjengset: not scanned. The worker assigned to them hit a usage limit before it reported, so this topic has no cross-check from them. - Unvetted, Rust Project Goals: the page calls the tool "broadly adopted by the Rust community" and plans to merge it into
cargo publish(Rust Project Goals: Continue resolving cargo-semver-checks blockers for merging into cargo, accepted for 2026). goals.rust-lang.org isn't on the roster or among its named references, so it supports nothing here.cargo-semver-checks' own documentation is a reference, not an unvetted source.
What this means for the repository
- No opinion covers the topic. Run
resolve-researchto createopinions/api-design.md. Its first sentence is the opening list here. It needs these sections: the breaking-change table, MSRV, features,#[non_exhaustive]and private fields, sealed traits, options structs, signatures, documentation, and the lint table. List it under README.md's Scope and in the layout tree, and changerust.md's pointer toapi-design.md, "which isn't written yet", to a link. Leave itserror-handling.mdpointer, which belongs to that topic. cargo-semver-checksneeds a second citable source before the opinion recommends it. Until then, the opinion can state the rules and the 1.94.1 evidence, and name the tool only in a sentence that says why it isn't the recommendation. Avet-sourcepass doesn't help here, because the gap is a citable source that names the tool, not a new author.harvest-sourcesshould watch for one, and for a Cargo Book or Rust Blog mention once the project goal is complete.- Lints for
templates/Cargo.toml, if the owner wants them.missing_docsandunreachable_pubgo in[workspace.lints.rust]. The template doesn't enableclippy::pedantic, somissing_errors_doc,missing_panics_doc,must_use_candidate, andreturn_self_not_must_useeach need their own line in[workspace.lints.clippy]. A library template turning onexhaustive_structsandexhaustive_enumsis a decision for the opinion. Each applies to libraries only, so a template that holds a binary crate needs them per crate, which belongs inproject-structure.md. ci.mdowns running the checks. Thecargo semver-checksstep, and verifyingrust-versionwith automated testing, belong there.- No
vet-sourcecandidate. The roster supported every claim except adopting the tool.