Should we change our `semver.md` process to manage _downstream_ effects of breaking changes?
Per discussion in !1129 (merged), Release.md
, and elsewhere, and explanations at https://github.com/dtolnay/semver-trick, sometimes a breaking change in a lower-level crate can cause a breaking change in any higher level crate that exposes even one type from the lower-level crate... even if the re-exposed type is not the one that broke.
As such, maybe we should:
- reconsider the frequency with which we make breaking changes that could instead be "new API, deprecate old API."
- consider refactoring crates that define important re-exported types so those types are instead defined in a different crate that changes only rarely.
- adjust our semver.md practices so that, if you make a breaking change in an API in crate X, you also have to note a
BREAKING,RE-EXPORTED
change in the every downstream crate that will break. (This process would be annoying, but it is equivalent to the process that we have to do when putting out a release. It might encourage people to look for a process other than API breaks.) - Declare that more things are not covered by semver.
- Try to re-export less, when we can.
Alternatively, we could:
- say that, for now, when we make a breaking change in any crate at a lower level than
arti-clent
, we simply assume that every higher-level crate other thanarti-client
will have broken too, and we don't bother to investigate.
I do acknowledge that we're still early in Arti's development, and breaking changes will happen and aren't too bad. Still, I think we should aim for a process that we'd be able to use long-term when Arti is more stable, since otherwise we won't notice cases where our design is getting in the way of the process we will eventually need.
Let's discuss!