I maintain the fltk-rs crate, which is currently at version 1.5.6 and is based on FLTK 1.4. Now, FLTK has begun development on version 1.5 (with some breaking changes), and I’d like to track those in fltk-rs (in a separate branch). Since these changes are breaking, SemVer suggests that I bump my crate’s major version from 1.x to 2.x. However, FLTK 1.5 itself is still in flux, so I’d like to release this work as a “pre-release” (e.g., 2.0.0-alpha.1, 2.0.0-alpha.2, etc.).
The catch is that Cargo (if I understand correctly) treats all 2.0.0-alpha.* releases as compatible with one another. If someone depends on ^2.0.0-alpha.1, they might automatically upgrade to 2.0.0-alpha.2 and get code-breaking changes unexpectedly. Alternatively, I could publish a “0.20.x” version to signal “unstable,” but that’s pretty unconventional after having released stable 1.x versions. It might also confuse users who see a new 0.x version after 1.x. Or would going with 2.0.0-alpha.1 then 2.0.1-alpha.1 etc be the better approach, eventually releasing version 2.0.0?
Any guidance or best practices on how to handle this scenario?
I personally would release 2.0.0-alpha.1, 2.0.0-alpha.2, etc.
This kind-of[1] shouldn't be unexpected, the Cargo book warns that this can happen:
Beware that pre-release versions can be unstable, and as such care should be taken when using them. Some projects may choose to publish breaking changes between pre-release versions. It is recommended to not use pre-release dependencies in a library if your library is not also a pre-release. Care should also be taken when updating your Cargo.lock, and be prepared if a pre-release update causes issues.
This comment is a really nice summary of the status quo. I especially like the suggestion for how users opting into a breaking pre-release version should specify the version requirement:
fltk = ">=2.0.0-alpha.1, <2.0.0-alpha.2"
I acknowledge that not everyone has read the Cargo book as rigorously as I did. ↩︎
Thank you for your reply and the link. I had gone through it previously and again after you reposted it, both times reading the whole discussion.
A point that was raised in the discussion was to rename the crate in the dev branch, for example fltk2 and start from 0.1.0.
The other issue I have is that I maintain several crates which also depend on fltk (for theming, layouts, extra widgets etc). Renaming to fltk2 should allow me to specify both fltk and fltk2 as optional dependencies and features, which will allow these crates to target either fltk or fltk2.