Keep Pre-Release Compatibility Intentional
RUST-KEEP-PRE-RELEASE-COMPATIBILITY-INTENTIONAL
Summary
Preserve pre-release compatibility only when it reflects a chosen contract. Early cleanup is often cheaper than freezing accidental names, re-exports, features, or variants.
Rule
Do not preserve accidental development-era compatibility in pre-release crates.
Why
Before a crate commits to stable public API, preserving accidental names, re-exports, features, or error variants can freeze poor shapes early. Pre-release cleanup is often cheaper than carrying compatibility shims that make the intended API harder to learn.
Cargo's versioning model treats 0.x compatibility differently from 1.x, but downstream users
can still depend on pre-release crates. The point is not to break users casually; it is to avoid
pretending an accidental development shape is a durable contract before the maintainer has chosen
that contract.
Helps
- Helps pre-release crates converge on intentional public shape before semver compatibility hardens.
Limits
Keep compatibility when real users already depend on the shape, migration cost is high, or the project has promised stability despite a pre-1.0 version. If you remove accidental compatibility, make the intended replacement clear in docs or release notes.
Agent Instruction
Clean up accidental pre-release Rust API compatibility after the intended API becomes clearer and
the crate has not promised the old shape.Mechanisms
Supported by semver review, changelog notes, migration examples, and public API diff tools.