You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+13-30
Original file line number
Diff line number
Diff line change
@@ -12,46 +12,29 @@ This project is developed and maintained by the [HAL team][team].
12
12
13
13
This is the suggested approach to adding a new trait to `embedded-hal`
14
14
15
-
### Discussion
15
+
### Research / Discussion
16
16
17
-
Ideally, before proposing a new trait, or set of traits, you should create an issue where the use
18
-
cases and requirements of the trait(s) are discussed.
17
+
Ideally, before proposing a new trait, or set of traits, you should check for an existing issue
18
+
suggesting the need for the trait, as well as any related works / use cases / requirements that
19
+
are useful to consider in the design of the trait.
19
20
20
-
These issues will be labeled as `discussion`s in the issue tracker.
21
+
These issues will be labeled as `discussion` in the issue tracker.
21
22
22
-
### Proposing a trait
23
-
24
-
Once there's consensus on the requirements of the trait(s) a new issue, or a PR, with a proposal
25
-
should be opened. The proposal should include the actual trait definitions as well as a link to the
26
-
issue with previous discussion, if there was one.
23
+
### Implementation / Demonstration
27
24
28
-
If the proposal includes more than one alternative then there should be further discussion to try to
29
-
single out the best alternative.
25
+
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.
30
26
31
-
These issues / PRs will be labeled as `proposal`s in the issue tracker.
27
+
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.
32
28
33
-
### Testing period
29
+
### Proposing a trait
34
30
35
-
If there are no objections to the proposal the new trait(s) will land behind the "unproven" Cargo
36
-
feature and an issue about the new trait(s) will be created. If the proposal includes several
37
-
alternatives and a single one couldn't be chosen as the best then each alternative will land behind
38
-
a different Cargo feature, e.g. "alt1" or "alt2".
31
+
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.
39
32
40
-
The traits will undergo a testing period before they move into the set of proven traits. During
41
-
this period users are encouraged to try to implement the unproven traits for their platforms and to
42
-
build drivers on top of them. Problems implementing the trait(s) as well as successful
43
-
implementations should be reported on the corresponding issue.
33
+
If there is determined to be more than one alternative then there should be further discussion to
34
+
try to single out the best option. Once there is consensus this will be merged into the `embedded-hal` repository.
44
35
45
-
To leave the unproven state at least *two* implementations of the trait(s) for different platforms
46
-
(ideally, the two platforms should be from different vendors) and *one* generic driver built on top
47
-
of the trait(s), or alternatively one demo program that exercises the trait (via generic function /
48
-
trait object), *should* be demonstrated. If, instead, reports indicate that the proposed trait(s)
49
-
can't be implemented for a certain platform then the trait(s) will be removed and we'll go back to
50
-
the drawing board.
36
+
These issues / PRs will be labeled as `proposal`s in the issue tracker.
51
37
52
-
Issues used to track unproven APIs will be labeled as `unproven-api`s in the issue tracker and they
53
-
may also include the labels `needs-impl` and `needs-driver` to signal what's required for them to
0 commit comments