From 48b75c52101e47f1044e335e5e7157fdb36c0905 Mon Sep 17 00:00:00 2001 From: Aleksey Kladov Date: Fri, 6 Nov 2020 13:03:38 +0100 Subject: [PATCH 1/4] Suggest MSRV policy I don't think there's a strong consensus here yet. However, there seems to be a weak consensus, and also de-facto practice for many popular crates (`cfg-if`, `lazy-static`). Additionally, there's a lot of continuous discussion and re-litigation across various forums and issue trackers. So it seems like tentatively documenting current practice might make sense? --- src/checklist.md | 2 ++ src/necessities.md | 35 +++++++++++++++++++++++++++++++++++ 2 files changed, 37 insertions(+) diff --git a/src/checklist.md b/src/checklist.md index 3f3d5ac..81baac2 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 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..b7a1269 100644 --- a/src/necessities.md +++ b/src/necessities.md @@ -109,3 +109,38 @@ 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 a 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 MSRV increases are reflected in the semver version of the crate? + +MSRV should be tested in CI. + +The API guidelines tentatively suggest that, for libraries, 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 sevmer-breaking changes. + +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 test +``` From f2acecc5dc04272ab27517205503289893fba45e Mon Sep 17 00:00:00 2001 From: Aleksey Kladov Date: Fri, 6 Nov 2020 17:38:18 +0100 Subject: [PATCH 2/4] Mention that bumping major on MSRV is not bad --- src/necessities.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/necessities.md b/src/necessities.md index b7a1269..7273f4d 100644 --- a/src/necessities.md +++ b/src/necessities.md @@ -137,6 +137,10 @@ update` workflow for older compilers. However, do not increase MSRV without a good reason, and, if possible, batch MSRV increases with sevmer-breaking changes. +Nonetheless, some crates intentionally choose to treat MSRV increase 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: From 830cfc0140f7bd66420463c95361d3d55a6e9987 Mon Sep 17 00:00:00 2001 From: Aleksey Kladov Date: Sat, 7 Nov 2020 11:46:57 +0100 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: Aramis Razzaghipour --- src/checklist.md | 2 +- src/necessities.md | 16 ++++++++-------- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/src/checklist.md b/src/checklist.md index 81baac2..cd05a76 100644 --- a/src/checklist.md +++ b/src/checklist.md @@ -72,7 +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 MSRV policy ([C-MSRV]) + - [ ] Crate has an MSRV policy ([C-MSRV]) [C-CASE]: naming.html#c-case diff --git a/src/necessities.md b/src/necessities.md index 7273f4d..8c99046 100644 --- a/src/necessities.md +++ b/src/necessities.md @@ -111,21 +111,21 @@ distribution of the crate itself, so a permissively-licensed crate should generally only depend on permissively-licensed crates. -## Crate has a MSRV policy (C-MSRV) +## 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 MSRV increases are reflected in the semver version of the crate? +* How are MSRV increases reflected in the semver version of the crate? -MSRV should be tested in CI. +Compliance with a crate’s stated MSRV should be tested in CI. -The API guidelines tentatively suggest that, for libraries, MSRV increase should +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 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 @@ -135,13 +135,13 @@ 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 sevmer-breaking changes. +MSRV increases with semver-breaking changes. -Nonetheless, some crates intentionally choose to treat MSRV increase as a semver +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 +To reliably test MSRV on CI, use a dedicated `Cargo.lock` file with dependencies pinned to minimal versions: ```bash From 38e610d13446dd81a09c81ec6121037706ee74d4 Mon Sep 17 00:00:00 2001 From: Aleksey Kladov Date: Thu, 19 Nov 2020 19:26:47 +0100 Subject: [PATCH 4/4] Exclude tests from MSRV testing recipe In practice, dev-deps often have much more lenient MSRV policy than then crate under test. Using `build` rather than `test` works around that. --- src/necessities.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/necessities.md b/src/necessities.md index 8c99046..d339270 100644 --- a/src/necessities.md +++ b/src/necessities.md @@ -146,5 +146,5 @@ pinned to minimal versions: ```bash $ cp ci/Cargo.lock.min ./Cargo.lock -$ cargo +$MSRV test +$ cargo +$MSRV build ```