embedded-io: API stability and 1.0.0 release

[elast0ny]

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.

[chrysn]

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?

[chrysn]

The core::Error step has been done in #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.)

[rursprung]

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)?

[chrysn]

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

[rursprung]

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)

[chrysn]

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

[rursprung]

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

[chrysn]

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?