Document SemVer hazards of `spi::Operation::DelayNs` - Githubissues

rust-embedded / embedded-hal

A Hardware Abstraction Layer (HAL) for embedded systems

Apache License 2.0

1.95k stars 197 forks source link

Document SemVer hazards of `spi::Operation::DelayNs` #552

Closed GrantM11235 closed 9 months ago

GrantM11235 commented 9 months ago

Imagine this timeline:

A driver author releases cool-driver 1.0.0 which uses SpiDevice but doesn't use DelayNs.
A user uses a SpiDevice impl from embedded_hal_bus with NoDelay. The user tests it and it works fine.
The driver author notices a timing problem and adds a DelayNs and releases it as cool-driver 1.0.1
The user updates cool-driver (maybe even by accident). It still compiles with no warnings.
The program panics at runtime.

Aside from making actual changes to the SpiDevice trait, I can only think of two possible "solutions":

Tell the author of cool-driver that by adding a DelayNs they have made a breaking change and they must release it as version 2.0.0 instead.
Tell the user that they shouldn't really use NoDelay, but if they do they must pin the version of any dependency that they use it with.

I don't really like either of these options, but I don't have any better ideas.

Dirbaio commented 9 months ago

opened #558 to address this. It picks solution 2, which is sort of what we agreed on when we added the "no delay" versions: it's theoretically semver-breaking but in practice it's going to be rare that a driver starts using delays if it wasn't before.