[RFC] Managing breaking changes to existing traits

[ryankurte]

As highlighted in #95, #97 and #99, there are likely to be situations in which we need to fix or upgrade traits in breaking ways, and these are likely to have significant ramifications on the embedded ecosystem. This RFC proposes an approach to manage these breaking changes.

Goals:

• Mitigate the downstream breakage caused by embedded-hal breaking changes
• Communicate breaking changes to give library uses an opportunity to update

Approach:

We propose a staged approach for managing breaking changes, with some time between each stage to allow API consumers to update.

In the first release, replacement traits are introduced and feature-gated allowing users to opt in to their use. Feature names start with with use- and a description of the change, for example use-fallible-digital-traits for the new fallible digital trait update in #97. Existing traits are marked #[deprecated] to alert users to the need to update, and this opt-in flag should be added to the CI build matrix. Documentation should also be updated to recommend the use of the opt-in traits and the related github issue for the change. This stage alerts HAL users of deprecation and allows immediate migration should they desire, without requiring any explicit action.

In the second release, the opt-in feature flag is replaced with an opt-out flag to allow regression to the previous trait if required, this should start with regress-. Continuing the fallible digital trait example this would be regress-infallible-digital-traits. This opt-out flag should be added to the build matrix, and the previous flag removed. Documentation should be updated to mention opt-out trait availability if required. This stage will break HAL consumers using the previous traits, requiring explicit action to update or defer the change.

In the third release, the old traits are removed, feature flags are removed from the package and the CI build matrix, and the documentation should be updated to remove mention of the opt-out trait. This stage will break any hal consumers that have not updated to the new traits.

In each release, these changes will be documented in the changelog (as is standard) and should be published through other useful means. The linking of the related issue in the documentation should allow for feedback from HAL consumers at each stage.
Each stage will correspond to a semver version increase (though it is worth noting that more than one breaking change may be included in a single release). At 0.x this will be patch, minor, minor, and >=1.x: will be minor, major, major.

I also wrote a small tool to analyse the dependency requirements, resolutions, and features of published crates (https://github.com/ryankurte/rust-dep-check), which would let us track migration through versions and feature flags. An example output showing the current use of embedded-hal:

Found 100 crates using 'embedded-hal'
Version requirements:
	^0.1	(0.1.3):	   1 / 100 (1.00 %)
	^0.1.0	(0.1.3):	   6 / 100 (6.00 %)
	^0.1.1	(0.1.3):	   1 / 100 (1.00 %)
	^0.1.2	(0.1.3):	   7 / 100 (7.00 %)
	^0.2	(0.2.1):	  19 / 100 (19.00 %)
	^0.2.0	(0.2.1):	  12 / 100 (12.00 %)
	^0.2.1	(0.2.1):	  45 / 100 (45.00 %)
	~0.2	(0.2.1):	   9 / 100 (9.00 %)
Features:
	unproven:	  35 / 100 (35.00 %)
Resolved versions and features:
	0.1.3:	  15 / 100 (15.00 %)
		unproven:	   3 / 15 (20.00 %)
	0.2.1:	  85 / 100 (85.00 %)
		unproven:	  32 / 85 (37.65 %)

Questions

• Should this apply to traits marked unproven? My view is that given the propensity of unproven traits we may as well try to mitigate all breakages or no worry about it at all (see the alternative).

Alternative

Do nothing, semver already mitigates breaking changes and we’re in the 0.x series with no API stability guarantees. This is much simpler, though not particularly supportive of our API consumers or the possible impact of breaking changes on the ecosystem, and it doesn't give our consumers any notice of the change outside of the github discussions.

cc. @hannobraun @therealprof

[jamwaffles]

I like the safety and caution of this approach, but it feel like it's more suited to post-1.0 quality software. What would the version numbers look like in the above process, semver-minor or semver-patch? I noticed you didn't define any timeframes for these releases. To keep things flowing, I think the deprecation process should be pretty quick at the stage the ecosystem is at now.

Personally, I'd prefer to have this stuff break catastrphically (as per the Alternative section) and fix it once, but I can see that causing a lot of pain for people with more embedded Rust written than myself.

[ryankurte]

[I] feel like it's more suited to post-1.0 quality software

I agree in principle, but I think if we want to get it right by 1.x we should start practicing it now and work out what works and doesn't. In addition, I suspect embedded-hal will not reach 1.0 for some time yet, and as the ecosystem grows this is going to become ever more important.

What would the version numbers look like in the above process

Roughly following the semver spec for breaking changes, so for 0.x: patch, patch, minor, and for >1.x: minor, minor, major. The first stage is not breaking and should be updated automatically to notify consumers, the second only requires a feature flag change to opt out, the third explicitly breaks anything not updated.

I can see an argument that the second two stages should both be considered breaking, the flags will have to be updated to work, and I'm not completely convinced either way. It's also important to note that there is likely to be than one change applied per release.

I noticed you didn't define any timeframes for these releases. To keep things flowing, I think the deprecation process should be pretty quick at the stage the ecosystem is at now.

Agreed that it should be quick. I'd like to see us iterating and releasing more regularly, and I think having some process like this would decrease the risk / scariness of releasing so we can do it faster. I think if we had a minimum limit of a couple of weeks between each stage we could have a similar release cadence.

This approach also lets us collect feedback on and learn from our releases / changes and the impact they have on our consumers, and to stop part way if there are issues, where breaking changes are otherwise not communicated except for the breakage.

[hannobraun]

I'm generally in favor. The one concern I have is what consequences this has on CI. If I understand correctly, all combinations of features will have to be tested. Could it cause problems to have that many CI builds (i.e. running up against usage limits)?

Roughly following the semver spec for breaking changes, so for 0.x: patch, patch, minor, and for >1.x: minor, minor, major.

I disagree with this part. Upgrading to a new patch (0.x) or minor version (>= 1.x) should never break the build (except to fix security issues). Even if the fix to the breaking change is as simple as adding a feature.

[therealprof]

@ryankurte Your primary plan sounds good to me.

[ryankurte]

Could it cause problems to have that many CI builds (i.e. running up against usage limits)?

I hope breaking migrations are not so frequent as to require many more builds.

Upgrading to a new patch (0.x) or minor version (>= 1.x) should never break the build (except to fix security issues)

Fair enough, do you have a preferred arrangement, or would you be happy with 0.x: patch, minor, minor, and >=1.x: minor, major, major? While it deviates from strict semver for 0.x, it benefits us if the first deprecation marking is an automatic upgrade.

[hannobraun]

Fair enough, do you have a preferred arrangement, or would you be happy with 0.x: patch, minor, minor, and >=1.x: minor, major, major? While it deviates from strict semver for 0.x, it benefits us if the first deprecation marking is an automatic upgrade.

I'd be very happy with that. I don't see how it deviates from semver. Adding a deprecation won't break the build, unless the crate denies warnings, which is effectively opting out of semver stability.

[eldruin]

This sounds very good @ryankurte.

1. It seems to me like there will be an increase of feature flags and it can become difficult to track the flags across releases.
   In this regard, I would add a list somewhere where the flags are registered, including in which release they will appear/disappear. A more condensed form of the Changelog, if you like, to ease the release process. Checking on this should be added to the release checklist.

2. We can have a first try at testing combinations of flags in the CI build in Make digital pin traits fallible #97. I only did this locally.

[hannobraun]

I just noticed @therealprof and @ryankurte having a discussion on IRC that they really should be having here, in my opinion :)

@therealprof said this:

That still doesn't allow mixing and matching which is a huge problem IMHO.
It requires the HAL implementation and all drivers to use the same version of the trait.

This brings up an issue that is hugely important in my opinion: You can't have multiple drivers among your dependencies that depend on different versions of the trait. If one driver enables the features, than all drivers that don't enable the feature are suddenly broken and won't build. Unless I miss something, there's no other way to fix the broken build than fork one group of drivers and change them to do what the other group of drivers is doing.

I think this makes all other advantages that this proposal has moot. What's the point of having a smooth transition, if everything breaks down the moment I use two drivers that are at different stages of the smooth transition?

In light of this, I now prefer the following approach:

• Add new trait variations under a new name (e.g. MyTrait2) deprecate the old trait (e.g. MyTrait) and publish a non-breaking release.
• On the next breaking release, replace MyTrait with MyTrait2, deprecate MyTrait2.
• On the next breaking release after that, remove MyTrait2.

Yes, that's one additional breakage, but at least it won't break my build if I mix two drivers.

That whole thought about mixing and matching drivers, has led me to another insight: It's possible to import different versions of the same package under different names: rust-lang/cargo#4953

That means, a HAL implementation can release a transition version that supports both and old and a new version, allowing application authors to use any driver during the transition period.

[therealprof]

After thinking about it some more and some discussion on IRC I have to revise my previous statement.

I see two fundamental problems with a part of this approach (the replacement traits and the feature gating of them):

1. In one application you can only have exactly one version of a trait and all components must adhere to that, i.e. the application, the HAL impl and all used drivers need to implement the exact same embedded-hal version with the same "version" of the trait. This can be annoying already when only the application and the HAL impl are involved but add a few drivers to the mix and this can easily turn into a blocker
2. Feature gating itself can be very annoying and should be used sparsely rather than generously. This begins with the question where to define the features (because removing a feature is a breaking change) and how to select them (if you have a hierarchy of crates there're multiple places where one could do this and this can easily lead to conflicting ideas of which features to use) leading up to the infamous global feature problem where all crates used in an application have to use the exact same features (cf. Disable default-features on rand dependency to avoid std version cortex-m-rt#107) even in different versions so each addition of new a new feature is potentially also a breaking change.

I'd really want to avoid a cfg gate hell of our own. The only alternatives I see here are:

• naming the new trait differently and slowly phasing out the old one
• simply replace it and release a new breaking version

[ryankurte]

Good points ^_^ I kindof figured breaking changes should be few and far between, and our goal would be to keep most of our environment in sync with the hal, but the rand crate experience seems not great.

In light of this, I now prefer the following approach:

• Add new trait variations under a new name (e.g. MyTrait2) deprecate the old trait (e.g. MyTrait) and publish a non-breaking release.
• On the next breaking release, replace MyTrait with MyTrait2, deprecate MyTrait2.
• On the next breaking release after that, remove MyTrait2.

I like that we'd be giving notice to consumers of depreciation, I don't like that we'd effectively be causing more breakage and thus fragmentation of dependencies.

That means, a HAL implementation can release a transition version that supports both and old and a new version, allowing application authors to use any driver during the transition period.

It seems to me that if there's a way we can do the work on our side it'd be better than expecting it of the whole ecosystem?

I just had a go at supporting both by including a previous hal version and writing adaptors (as suggested by @therealprof I think, but I may have misunderstood the suggestion), but, it seems like it would become a bit of a nightmare to manage if we ever had overlapping breakages / dependency requirements.

naming the new trait differently and slowly phasing out the old one

How would you approach this? I don't love the idea of version numbers in the api.

simply replace it and release a new breaking version

Pretty onboard with this, we have a common understanding with semver of what a version number change means, it's simple for us and easy to understand, and it only breaks once.