diff --git a/rfcs/0000-msrv-2020.md b/rfcs/0000-msrv-2020.md new file mode 100644 index 00000000..b17a397e --- /dev/null +++ b/rfcs/0000-msrv-2020.md @@ -0,0 +1,105 @@ +- Feature Name: msrv-2020 +- Start Date: 2020-04-28 +- RFC PR: (leave this empty) +- Rust Issue: (leave this empty) + +# Summary +[summary]: #summary + +This RFC proposes an update to the [current MSRV policy]. + +[current MSRV policy]: https://github.com/rust-embedded/wg/blob/8eb6488fdb16e92e70b074acc2fcf249b3edc70b/ops/msrv.md + +# Motivation +[motivation]: #motivation + + + +As part of the push to take [foundational crates to 1.0] releases, it has become necessary to be more exact on our guarantees to support versions of the Rust compiler. This discussion [has been contentious] in the past, sparking significant discussions in many meetings. + +In particular, it has been necessary to balance the (somewhat opposed) concerns of: + +1. Some users may find themselves stuck on old versions of the compiler, due to company restrictions, slow moving distribution/package managers, or regulatory concerns. +2. We maintain these crates on a volunteer basis, and our time is limited to focus on maintenance + +The following proposed policy aims to be a "good in most cases" solution, to support the largest subset of users and their typical usage practices. + +[foundational crates to 1.0]: https://github.com/rust-embedded/wg/issues/383 +[has been contentious]: https://github.com/rust-embedded/wg/issues/427 + +# Detailed design +[design]: #detailed-design + + + +First, let's start with the "what" of the policy, what are our rules? + +> NOTE: These rules apply only to released versions of the WG crates, not necessarily the tip of the `main` branch. + +* **Required Versions**: Crates maintained by the Embedded WG must always compile on the three most recent stable semver-minor compiler versions. + * e.g. if the current version is `1.50.1`, all WG crates must build with `1.48.*`, `1.49.*`, and `1.50.*`. +* **Minimum Supported Rust Version (MSRV)**: All crates maintained by the Embedded WG must state their **MSRV** in their project README. This must be a version less than or equal to the smallest current **Required Version**. + * The MSRV is inclusive of any possible feature of the crate, as well as the MSRV of all dependencies, unless otherwise specified. +* **Versioning Bump**: When incrementing the **MSRV** of a crate, the crate must make a semver-minor version increment. + * ex 1: For a crate that is version `1.2.3`, it must then go to version `1.3.0`. + * ex 2: For a crate that is version `0.4.5`, it must then go to version `0.4.6`. +* **Best Practices**: When possible, care should be taken to avoid a **Versioning Bump**. However, a **Versioning Bump** is always possible if the above conditions are met, particularly when maintainability of the crate or code simplicity would be improved. + + +Then, let's look at the "how" of the policy: + +* The **MSRV** should be stated in the project README. +* The **MSRV** should be tested using CI. Including: + * Per-commit/per-PR testing + * Periodic CI testing of released crates +* If a WG crate begins failing due to a dependency using new features of Rust, the WG crate should issue a semver-trivial release setting a maximum version of that dependency. Additionally, the WG crate may consider making a **Versioning Bump** without setting the maximum version of that dependency. +* Pull requests that *lower* the MSRV will be accepted. However, if the **MSRV** is reduced, a new **Versioning Bump** will be required to increase it again. Example: + * A WG crate has an **MSRV** of `1.50.0`, and a version of `1.2.5`. + * A change is made that requires a new version of Rust. + * The WG crate updates its **MSRV** to `1.52.0`, and its version to `1.3.0`. + * A PR is submitted to lower the **MSRV** to `1.50.1`. + * The WG crate updates its **MSRV** to `1.50.1`, and its version to `1.3.1`. + * A change is made that raises the **MSRV** to `1.52.0` again. + * The WG crate updates its **MSRV** to `1.52.0`, and its version to `1.4.0`. +* When necessary or desired, a crate may consider supporting multiple "release trains" simultaneously. For example, it may decide to maintain a version of `1.4.x` that supports **MSRV** `1.50.0`, and a version of `1.5.x` that supports **MSRV** `1.52.0`. This is up to the maintainers of that crate. +* For users that are sensitive to **MSRV** changes, we should suggest that they specify the Major and Minor semver version, e.g. `version = "1.5.*"`. +* For all other users, we should suggest they specify only the Major semver version, e.g. `version = "1.*"`. + +# How We Teach This +[how-we-teach-this]: #how-we-teach-this + + + +We will need to take the following actions: + +1. Update the [MSRV Operational Notes](./../ops/msrv.md) +2. Ensure all crates test their current MSRV + +# Drawbacks +[drawbacks]: #drawbacks + +The MSRV process is hugely time consuming to maintain, discuss, and decide. Likely, it currently provides little-to-no-value for most users. + +Although the process detailed above is comprehensive as far as we know today, it is likely to have unexpected edge cases that will require refinement. + +# Alternatives +[alternatives]: #alternatives + +The primary alternative to this is to abolish the management of MSRV for Embedded Rust WG projects. This would simplify the effort of managing these releases and projects, however for esoteric users that are restricted to an old version of the compiler, this would require extra effort on their part to maintain or use the crates in question. + +# Unresolved questions +[unresolved]: #unresolved-questions + +At the moment, there are no open unresolved questions.