rust-embedded
embedded-io: API stability and 1.0.0 release
Hello, I'm working on a project that is considering using embedded-io's traits for no_std environments and had some concerns about the stability of the API.
For example, the popular postcard serde format supports embedded-io traits but only from version 0.4.0. This means that I either have to commit to an old version to use postcard or make a fork of postcard (and upstream fixes ideally).
I assume this is a decision that anyone in the no_std ecosystem has to make if they want to be generic over Read/Write.
Is there any chance that embedded-io could take a stance on backwards compatibility of its Read/Write traits (as a statement in a README perhaps) and make a release of major version 1 ?
I understand that the crate may not be in such a state to be stable "forever" but if so, it would provide much more confidence in committing to using it.
We'll have at least one more breaking change when Error becomes a subtrait of core::Error. I'm also not sure WriteReady are ready (ha!) for prime time.
Maintainers, we use this issue as a tracking issue to list what has to be done before -io 1.0?
The core::Error step has been done in https://github.com/rust-embedded/embedded-hal/pull/630 -- so the next embedded-io release is breaking.
But is there anything else to do? I think not. (The Error change was also the only effectful change since 0.6.1 of late 2023.)
it'd be great to know if anything is missing from v0.6 or if we could release v1.0 (+ using the semver trick to avoid ripple effects)?
Right, as you say: that PR added core::error::Error impls, but no requirements on the associated types or the embedded-io trait.
Should we do one more braking change before (or as) we ge to 1.0, to add that requirement? After all, from a post-1.81 perspective, the current requirements to have an own error trait that does not impl core::error::Error is a bit odd.
I'm softly in favor of doing one more breaking change -- but we should get to a decision if we want to change anything any more at all (and not changing the Error requirements sets a pretty high bar for any other changes).
as a breaking change for v1.0 we should bump defmt to v1 and (probably?) rename the defmt-03 feature to just defmt (since defmt is not supposed to ever hit v2)
defmt also did the semver trick, so as long as we update the dependency to 0.3.100, we can have the public dependency on ^1. (Sure, if we do breaking changes, renaming the feature and going for just-1.0 would be prudent).
yeah, the bump to defmt v1 isn't a semver issue (due to defmt using the semver trick); renaming the defmt-03 to defmt feature is. i don't think carrying defmt-03 as a feature name into embedded-io(-async) v1.0 makes a lot of sense
With #672 merged, we're now on the "there'll be one breaking release at least before 1.0" track (eg. a 0.7 which then hopefully semver-tricks up to 1.0).
#673 is in the review pipeline, those are so far the only changes that came up for a 0.7.
Doing a 0.7 release would realistically pull with it a parallel 0.7 release of embedded-io-async (updated error trait) and embedded-io-adapters (just bumping its public dependency). Especially for -async I don't think that'd follow on the 1.0 path (I have a hunch we might want to have a means of doing .write_ready().await.write() that is not itself async, thus not requiring having a buffer that spans an await point), probably not -adapters either (no hurry there, it's not something one would pub-use).
How long should 0.7 stay 0.7 before there can be a conclusion that no further changes will be needed and a 1.0 can be released?