Skip to content

Commit 3f22b00

Browse files
bors[bot]ryankurte
andauthored
Merge #197
197: Updated readme with new process r=therealprof a=ryankurte Updated process from [hal-meeting](https://hackmd.io/ck-xRXtMTmKYXdK5bEh82A?view) Co-authored-by: ryan <[email protected]> Co-authored-by: Ryan <[email protected]>
2 parents e82ddb8 + d6a9166 commit 3f22b00

File tree

1 file changed

+13
-30
lines changed

1 file changed

+13
-30
lines changed

README.md

+13-30
Original file line numberDiff line numberDiff line change
@@ -12,46 +12,29 @@ This project is developed and maintained by the [HAL team][team].
1212

1313
This is the suggested approach to adding a new trait to `embedded-hal`
1414

15-
### Discussion
15+
### Research / Discussion
1616

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.
1920

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.
2122

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
2724

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.
3026

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.
3228

33-
### Testing period
29+
### Proposing a trait
3430

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.
3932

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.
4435

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.
5137

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
54-
move to the set of proven traits.
5538

5639
## Implementations and drivers
5740

0 commit comments

Comments
 (0)