Push foundational crates to 1.0

[jamesmunns]

We would like to push embedded crates owned by the working group to a stable 1.0 state, when reasonably possible.

Possible crates to evaluate include:

• cortex-m
• cortex-m-rt
• embedded-hal

For each crate, we should come up with our process of deciding whether these crates are ready. This could include evaluation, a call for feedback, or could require identification of tasks required before ready for stabilization. This may spawn one or more focus projects.

For now, we need to do the following:

• [ ] Enumerate crates that can be included in the 1.0 push
• [ ] Come up with a process or evaluation criteria before marking them 1.0

In the 2020-01-07 meeting we agreed to try and push a crate out on a six week cycle (although not aligned with the Rust release process - just inspired by it).

First Wave - ships Tuesday, 2020-02-18

• [x] r0 - https://github.com/rust-embedded/r0/issues/9

Second Wave

(Need to select from some of the following)

• [ ] cortex-m-rt - https://github.com/rust-embedded/cortex-m/issues/405
• [x] bare-metal - https://github.com/rust-embedded/bare-metal/issues/22
• [x] nb - https://github.com/japaric/nb/issues/20 (note, this is a @japaric crate)
• Anything else r0 unblocks

Future Waves

• [ ] cortex-m - https://github.com/rust-embedded/cortex-m/issues/183
• [x] embedded-hal - https://github.com/rust-embedded/embedded-hal/issues/177
• [ ] svd2rust - https://github.com/rust-embedded/svd2rust/issues/426
• [ ] cortex-m-semihosting - https://github.com/rust-embedded/cortex-m/issues/290

[IGBC]

SVD2Rust?

[thejpster]

SVD2Rust?

Done

[jonas-schievink]

• cortex-m-semihosting (like it or not)
• nb (since it's a public dependency of embedded-hal)

Also, before releasing any crate as 1.0, the crate should've gone through an exhaustive review of the API Guidelines (any deviations from the guidelines should be made consciously).

[thejpster]

* `cortex-m-semihosting` (like it or not)
* `nb` (since it's a public dependency of `embedded-hal`)

Tickety tick.

Also, before releasing any crate as 1.0, the crate should've gone through an exhaustive review of the API Guidelines (any deviations from the guidelines should be made consciously).

Agreed.

[jonas-schievink]

As part of this effort, would it make sense to push embedded targets (at least ARMv7-M / thumbv7*) towards tier-1 support in Rust? Personally I'd love to see that happen, and making that a part of the 1.0 push makes sense from a marketing perspective to me.

There's also some non-crate-specific things that might need some discussion from the entire WG before going 1.0 with some crates: https://github.com/rust-embedded/wg/issues/418

[arrowcircle]

Just a little not, all of these repos, except cortex-m-rt, does not have at least one test. It looks like a good hygienic thing to have at least minimal set of unit tests. Any ideas on that?

[jonas-schievink]

r0 has tests, nb has tests, embedded-hal has tests, bare-metal has a compile-fail test and otherwise no API that really needs testing. cortex-m should indeed have more tests, possibly running in Qemu, same for semihosting but we might deprecate that crate instead.

[adamgreig]

Just to add some more very commonly used embedded crates: the panic handlers (panic-halt, panic-abort, panic-semihosting, etc) would be nice to get to 1.0 as well.

[arrowcircle]

@jonas-schievink r0 have 2 tests inside src folder (thought it should go to tests). nb (japaric/nb) does not have any tests. embedded-hal does not have any tests. Maybe we talking about different things?

[jonas-schievink]

nb has extensive doctests, embedded-hal has tests for adapter impls, doctests, and otherwise only defines traits that cannot really be tested in a useful way. If you think any specific test coverage is lacking, please comment on the 1.0 tracking issue in the specific repo.

[arrowcircle]

@jonas-schievink I checked nb and embedded-hal repos. They both have travis ci set up, but have no badges in the readme. Travis scripts runs successfully, but I was unable to run simple cargo test on my laptop (mac os x).

I think badges and good readme is essential for open source projects, and most of rust embedded repos have nothing of this.

Should I create pull requests?

[jonas-schievink]

I don't really have much to do with either of those crates, but CI badges are at best useless for rust-embedded crates (CI always passes since we use bors), and at worst misleading (the link always points to the state of master, even when on a maintenance branch), so I don't think we should add them.

[arrowcircle]

@jonas-schievink Could You please tell me more why CI always passes because of bors? You mean it will prohibit pull request from merge if CI is not passing?

Readme is where I see big problem and You dont. Most of the rust repos have horrible readme. Most of them have same template, from which you cant get any idea what is what. Also, I've seen some articles, that OSS repo with bad readme (no badges, no working quickstart examples, no clear description why repo is needed) have less chances to be good, have less changes to have pull request from outside people and so on.

We can compare something like https://github.com/ai/nanoid (or more popular https://github.com/webpack/webpack) and any rust embedded repo and see the difference.

And thing is, that nobody cares about that. If you are not in rust embedded wg, you have no change to get whats happening. WG looks like some secret society with secret messenger and cryptic docs. What chances, that people outside WG will send pull requests?

[jonas-schievink]

@arrowcircle Let's move that discussion somewhere else, I don't think this tracking issue is the right place. I don't disagree about the readme situation by the way, not sure why you think that. I just have limited time and energy to improve them.

[Sympatron]

r0, bare-metal and nb are now 1.0 and can be ticked off for reference.