diff --git a/src/checklist.md b/src/checklist.md index 3f3d5ac..cd05a76 100644 --- a/src/checklist.md +++ b/src/checklist.md @@ -72,6 +72,7 @@ - **Necessities** *(to whom they matter, they really matter)* - [ ] Public dependencies of a stable crate are stable ([C-STABLE]) - [ ] Crate and its dependencies have a permissive license ([C-PERMISSIVE]) + - [ ] Crate has an MSRV policy ([C-MSRV]) [C-CASE]: naming.html#c-case @@ -139,3 +140,4 @@ [C-STABLE]: necessities.html#c-stable [C-PERMISSIVE]: necessities.html#c-permissive +[C-MSRV]: necessities.html#c-msrv diff --git a/src/necessities.md b/src/necessities.md index de32ce2..d339270 100644 --- a/src/necessities.md +++ b/src/necessities.md @@ -109,3 +109,42 @@ cannot be used in some situations where most of the Rust runtime stack can. The license of a crate's dependencies can affect the restrictions on distribution of the crate itself, so a permissively-licensed crate should generally only depend on permissively-licensed crates. + + +## Crate has an MSRV policy (C-MSRV) + +A crate should clearly document its Minimal Supported Rust Version: + +* Which versions versions of Rust are supported now? +* Under what conditions is MSRV increased? +* How are MSRV increases reflected in the semver version of the crate? + +Compliance with a crate’s stated MSRV should be tested in CI. + +The API guidelines tentatively suggest that, for libraries, an MSRV increase should +*not* be considered a semver-breaking change. Specifically, when increasing +MSRV: + +* for crates past `1.0.0`, increment minor version (`1.1.3` -> `1.2.0`), +* for crates before `1.0.0`, increment patch version (`0.1.3` -> `0.1.4`). + +This reduces the amount of ecosystem-wide work for MSRV upgrades and prevents +incompatibilities. It also is a de-facto practice for many cornerstone crates. +This policy gives more power to library consumers to manually select working +combinations of library and compiler versions, at the cost of breaking `cargo +update` workflow for older compilers. + +However, do not increase MSRV without a good reason, and, if possible, batch +MSRV increases with semver-breaking changes. + +Nonetheless, some crates intentionally choose to treat MSRV increases as a semver +breaking change. This is also a valid strategy, but it is not recommended as the +default choice. + +To reliably test MSRV on CI, use a dedicated `Cargo.lock` file with dependencies +pinned to minimal versions: + +```bash +$ cp ci/Cargo.lock.min ./Cargo.lock +$ cargo +$MSRV build +```