The semver trick is not backwards compatible if you wait
On November 18, 2026 by Sosthène Guédon
The Rust ecosystem relies a lot on semver to make it easy to update dependencies without spending hours each time refactoring the code that uses them.
Sometimes, as a library developer, you want to do a breaking change in a small part of your library. There is a way to do a semver-breaking change, while at the same time avoiding a split in the ecosystem downstream. It is called the semver trick.
Imagine you have a library called mylib, that exports two structs MainStruct and DeprecatedStruct, published under version 0.1.0.
You want to publish 0.2.0, where DeprecatedStruct is removed. The trick is simple:
- Publish
0.2.0as you want it to be - Publish a version
0.1.1that keepsDeprecatedStruct, but, forMainStruct, you add version0.2.0as a dependency, and re-exportMainStructfrom it.
This gives you the best of both worlds. You've been able to get rid of your deprecated structures, but crates that depend on version 0.2.0 or version 0.1.1 of MainStruct will be able to just work with each other. This avoids a painful ecosystem-wide migration.
However, for this trick to be truly without breaking change, you must publish both 0.1.1 and 0.2.0 in a very short timeframe. If you wait (for example several days), you risk breaking some downstreams.
Imagine there is a library called some-traits that depends on 0.1.0 to implement the traits on MainStruct. When the author sees your release 0.2.0, they might anticipate the ecosystem split, and, to be "neutral", adds 0.2.0 as an optional dependency behind a feature-flag, to implement the traits on its MainStruct too.
Now, a couple of days later, you publish 0.1.1. This breaks some-traits. If you enable all its features, the implementations of traits of MainStruct will be there twice, for both versions of the struct, but now they are referring to the same struct, leading to conflicting implementations.
The moral is, if you consider doing the semver trick you must do it when you first release the breaking change. If you've already published it, it might be too late not to cause ecosystem breakage.