Skip to content

Commit 178f66b

Browse files
bors[bot]eldruin
bors[bot]
and
eldruin
authored
Merge #368
368: Document MSRV upgrade and improve readme r=ryankurte a=eldruin I moved some of the sections in the README out into separate documents in a `docs` folder. I have left the section about alpha releases in there, though. I think it is important enough to grant it its placement. I have added a document describing a policy to upgrade the MSRV, since this will eventually be important once we have released the `1.0.0` version. TL;DR: The MSRV may be updated in major or minor releases but not on patch releases. Closes #364 Co-authored-by: Diego Barrios Romero <[email protected]>
2 parents a3522db + de8afed commit 178f66b

File tree

4 files changed

+100
-43
lines changed

4 files changed

+100
-43
lines changed

‎README.md

Lines changed: 18 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ these drivers for their platform.
3030

3131
For functionality that goes beyond what is provided by `embedded-hal`, users are encouraged
3232
to use the target platform directly. Abstractions of common functionality can be proposed to be
33-
included into `embedded-hal` as described [below](#how-to-add-a-new-trait), though.
33+
included into `embedded-hal` as described [in this guide](docs/how-to-add-a-new-trait.md), though.
3434

3535
See more about the design goals in [this documentation section](https://docs.rs/embedded-hal/latest/embedded_hal/#design-goals).
3636

@@ -43,64 +43,39 @@ They are provided as early previews for community testing and preparation for th
4343
If you use an alpha release, we recommend you choose an exact version specification in your
4444
`Cargo.toml` like: `embedded-hal = "=1.0.0-alpha.2"`
4545

46-
See below for a way to implement both an `embedded-hal` `0.2.x` version and an `-alpha` version
47-
side by side in a HAL.
46+
See [this guide](docs/version-policy.md) for a way to implement both an `embedded-hal` `0.2.x`
47+
version and an `-alpha` version side by side in a HAL.
4848

4949
[#177]: https://github.com/rust-embedded/embedded-hal/issues/177
5050

51-
## How-to: add a new trait
52-
53-
This is the suggested approach to adding a new trait to `embedded-hal`
54-
55-
### Research / Discussion
56-
57-
Ideally, before proposing a new trait, or set of traits, you should check for an existing issue
58-
suggesting the need for the trait, as well as any related works / use cases / requirements that
59-
are useful to consider in the design of the trait.
60-
61-
These issues will be labeled as `discussion` in the issue tracker.
62-
63-
### Implementation / Demonstration
64-
65-
Proposed traits should then be implemented and demonstrated, either by forking `embedded-hal` or by creating a new crate with the intent of integrating this into `embedded-hal` once the traits have stabilized. You may find [cargo workspaces](https://doc.rust-lang.org/book/ch14-03-cargo-workspaces.html) and [patch](https://doc.rust-lang.org/edition-guide/rust-2018/cargo-and-crates-io/replacing-dependencies-with-patch.html) useful for the forking approach.
66-
67-
Traits should be demonstrated with at least *two* implementations on different platforms and *one* generic driver built on the trait. Where it is possible we suggest an implementation on a microcontroller, and implementation for [linux](https://github.com/rust-embedded/linux-embedded-hal), and a driver (or drivers where requirements are more complex) with bounds using the trait.
68-
69-
### Proposing a trait
70-
71-
Once the trait has been demonstrated a PR should be opened to merge the new trait(s) into `embedded-hal`. This should include a link to the previous discussion issue.
72-
73-
If there is determined to be more than one alternative then there should be further discussion to
74-
try to single out the best option. Once there is consensus this will be merged into the `embedded-hal` repository.
75-
76-
These issues / PRs will be labeled as `proposal`s in the issue tracker.
51+
## Documents
7752

53+
- [How-to: add a new trait](docs/how-to-add-a-new-trait.md)
54+
- [Version policy](docs/version-policy.md)
55+
- [MSRV](docs/msrv.md)
7856

7957
## Implementations and drivers
8058

81-
For a list of `embedded-hal` implementations and driver crates check the [awesome-embedded-rust]
82-
list.
83-
84-
[awesome-embedded-rust]: https://github.com/rust-embedded/awesome-embedded-rust#driver-crates
85-
86-
### Supporting different (alpha and non-alpha) HALs
59+
For a non-exhaustive list of `embedded-hal` implementations and driver crates check the
60+
[awesome-embedded-rust] list.
8761

88-
[embedded-hal-compat](https://github.com/ryankurte/embedded-hal-compat) provides shims
89-
to support interoperability between the latest `0.2.x` and `1.0.0-alpha.N` HALs, allowing one to use
90-
incompatible HAL components (generally) without alteration.
91-
See the [docs](https://docs.rs/embedded-hal-compat/) for examples.
62+
You may be able to find even more HAL implementation crates and driver crates by searching for the
63+
[`embedded-hal-impl`], [`embedded-hal-driver`] and [`embedded-hal`][embedded-hal-kw] keywords
64+
on crates.io.
9265

93-
It is also possible for HAL implementations to support both the latest `0.2.x` and `1.0.0-alpha.N` versions
94-
side by side, for an example see [LPC8xx HAL](https://github.com/lpc-rs/lpc8xx-hal).
66+
[`embedded-hal-impl`]: https://crates.io/keywords/embedded-hal-impl
67+
[`embedded-hal-driver`]: https://crates.io/keywords/embedded-hal-driver
68+
[embedded-hal-kw]: https://crates.io/keywords/embedded-hal
9569

96-
Note that `embedded-hal` `-alpha` versions are a moving target and _not guaranteed_ to be compatible.
97-
Because of this we only aim to support the latest `-alpha`.
70+
[awesome-embedded-rust]: https://github.com/rust-embedded/awesome-embedded-rust#driver-crates
9871

9972
## Minimum Supported Rust Version (MSRV)
10073

10174
This crate is guaranteed to compile on stable Rust 1.54 and up. It *might*
10275
compile with older versions but that may change in any new patch release.
10376

77+
See [here](docs/msrv.md) for details on how the MSRV may be upgraded.
78+
10479
## License
10580

10681
Licensed under either of

‎docs/how-to-add-a-new-trait.md

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# How-to: add a new trait
2+
3+
This is the suggested approach to adding a new trait to `embedded-hal`
4+
5+
## Research / Discussion
6+
7+
Ideally, before proposing a new trait, or set of traits, you should check for an existing issue
8+
suggesting the need for the trait, as well as any related works / use cases / requirements that
9+
are useful to consider in the design of the trait.
10+
11+
These issues will be labeled as `discussion` in the issue tracker.
12+
13+
## Implementation / Demonstration
14+
15+
Proposed traits should then be implemented and demonstrated, either by forking `embedded-hal` or by creating a new crate with the intent of integrating this into `embedded-hal` once the traits have stabilized. You may find [cargo workspaces](https://doc.rust-lang.org/book/ch14-03-cargo-workspaces.html) and [patch](https://doc.rust-lang.org/edition-guide/rust-2018/cargo-and-crates-io/replacing-dependencies-with-patch.html) useful for the forking approach.
16+
17+
Traits should be demonstrated with at least *two* implementations on different platforms and *one* generic driver built on the trait. Where it is possible we suggest an implementation on a microcontroller, and implementation for [linux](https://github.com/rust-embedded/linux-embedded-hal), and a driver (or drivers where requirements are more complex) with bounds using the trait.
18+
19+
## Proposing a trait
20+
21+
Once the trait has been demonstrated a PR should be opened to merge the new trait(s) into `embedded-hal`. This should include a link to the previous discussion issue.
22+
23+
If there is determined to be more than one alternative then there should be further discussion to
24+
try to single out the best option. Once there is consensus this will be merged into the `embedded-hal` repository.
25+
26+
These issues / PRs will be labeled as `proposal`s in the issue tracker.

‎docs/msrv.md

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# Minimum Supported Rust Version (MSRV)
2+
3+
This crate is guaranteed to compile on all stable Rust versions going back to
4+
the version stated as MSRV in the README. It *might* compile with even older versions but
5+
that may change in any new patch release.
6+
7+
## How the MSRV will be upgraded
8+
9+
For `embedded-hal`, we do not consider upgrading the MSRV a strictly breaking change as defined by
10+
[SemVer](https://semver.org).
11+
12+
We follow these rules when upgrading it:
13+
14+
- We will not update the MSRV on any patch release: \_.\_.*Z*.
15+
- We may upgrade the MSRV on any *major* or *minor* release: *X*.*Y*.\_.
16+
- We may upgrade the MSRV in any preliminary version release (e.g. an `-alpha` release) as
17+
these serve as preparation for the final release.
18+
- MSRV upgrades will be clearly stated in the changelog.
19+
20+
This applies both to `0._._` releases as well as `>=1._._` releases.
21+
22+
For example:
23+
24+
For a given `x.y.z` release, we may upgrade the MSRV on `x` and `y` releases but not on `z` releases.
25+
26+
If your MSRV upgrade policy differs from this, you are advised to specify the
27+
`embedded-hal` dependency in your `Cargo.toml` accordingly.
28+
29+
See the [Rust Embedded Working Group MSRV RFC](https://github.com/rust-embedded/wg/blob/master/rfcs/0523-msrv-2020.md)
30+
for more background information and reasoning.

‎docs/version-policy.md

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Version policy
2+
3+
At the moment we are working towards a `1.0.0` release (see [#177]). During this process we will
4+
release alpha versions like `1.0.0-alpha.1` and `1.0.0-alpha.2`.
5+
Alpha releases are **not guaranteed** to be compatible with each other.
6+
They are provided as early previews for community testing and preparation for the final release.
7+
If you use an alpha release, we recommend you choose an exact version specification in your
8+
`Cargo.toml` like: `embedded-hal = "=1.0.0-alpha.2"`
9+
10+
See below for a way to implement both an `embedded-hal` `0.2.x` version and an `-alpha` version
11+
side by side in a HAL.
12+
13+
[#177]: https://github.com/rust-embedded/embedded-hal/issues/177
14+
15+
## Supporting different (alpha and non-alpha) HALs
16+
17+
[embedded-hal-compat](https://github.com/ryankurte/embedded-hal-compat) provides shims
18+
to support interoperability between the latest `0.2.x` and `1.0.0-alpha.N` HALs, allowing one to use
19+
incompatible HAL components (generally) without alteration.
20+
See the [docs](https://docs.rs/embedded-hal-compat/) for examples.
21+
22+
It is also possible for HAL implementations to support both the latest `0.2.x` and `1.0.0-alpha.N` versions
23+
side by side, for an example see [LPC8xx HAL](https://github.com/lpc-rs/lpc8xx-hal).
24+
25+
Note that `embedded-hal` `-alpha` versions are a moving target and _not guaranteed_ to be compatible.
26+
Because of this we only aim to support the latest `-alpha`.

0 commit comments

Comments
 (0)