Semver and Evolution of Traits and Impls

Which changes to traits, impls and public types break downstream code, following the Cargo book's SemVer compatibility chapter and RFC 1105 (API evolution). "Major" means a new major version (or a new minor version below 1.0); "possibly breaking" means it can break some callers in practice, usually through name collisions or type inference, and is conventionally allowed in a minor release.

#Contents

• Trait changes
• Impl changes
• Generic bounds and parameters
• Public types
• Auto traits leak
• Designing for evolution
• Checking before release

#Trait changes

Seal traits that users only consume, so you can add required methods later. Leave traits open only when downstream implementations are the point (plugins, backends, codecs).

#Impl changes

#Generic bounds and parameters

#Public types

#[non_exhaustive] on public error enums and config structs (built through constructors or builders) keeps future additions minor. Callers must then write _ => arms and cannot use struct literals.

#Auto traits leak

Send, Sync, Unpin, UnwindSafe and RefUnwindSafe are inferred from fields and from the concrete type behind impl Trait. They are part of your public API even though you never wrote them:

• Adding an Rc, RefCell, raw pointer or !Send guard field to a public struct removes Send/Sync: major.
• Changing what an -> impl Future returns so it holds a !Send value across an .await removes Send from the opaque type: major for callers who spawned it.
• Guard against accidents with compile-time assertions (see testing-trait-designs.md):

pub struct Client { inner: std::sync::Arc<std::sync::Mutex<Vec<u8>>> }

const _: () = {
    const fn assert_send_sync<T: Send + Sync>() {}
    assert_send_sync::<Client>();
};

#Designing for evolution

1. Seal consumer-only traits (pub trait Codec: private::Sealed).
2. Give new trait methods defaults, and prefer names unlikely to collide.
3. Put constructors and generic helpers behind where Self: Sized so the trait stays dyn-compatible as it grows.
4. Mark error enums and option structs #[non_exhaustive] from the first release.
5. Return opaque types (impl Iterator, newtypes) instead of concrete std/foreign types, so the implementation can change.
6. Keep foreign types out of public signatures when they have their own semver (a reqwest::Error in your API ties your major version to theirs); wrap them.
7. Implement From (not Into) and keep the set of From impls deliberate: each one is a commitment and a possible inference hazard.

#Checking before release

• cargo semver-checks compares the public API against the last published version and reports many of the breaking changes above (removed items, new required trait items, enum variants, auto-trait changes).
• cargo public-api diff (nightly rustdoc JSON) shows the full public surface change.
• Run downstream crates' test suites (crater-style) for widely used libraries.
• Write the change into CHANGELOG.md with its classification.