Alpha/beta/rc with Cargo & semantic versioning

I wonder how are the exact rules when specifying alpha/beta/rc versions in the [dependencies] section of a Cargo.toml file.

I found this section in the Cargo book, but it leaves me with some questions:

  • Are the rules well defined, or subject to change (there is a 6 year old open ticket on that matter)?
  • Can 1.0.0-beta.5 update to 1.0.0-beta.6 but not to 1.0.0?
  • Are "alpha", "beta", "rc" special identifiers, or do they just "naturally" sort correctly because 'a' < 'b' < 'r'?
1 Like

I believe when the best place to find information about the semantics of semver is the semver crate, which references semver.org.

The section Specifying Dependencies states that Cargo's rules differ from SemVer:

This compatibility convention is different from SemVer in the way it treats versions before 1.0.0. While SemVer says there is no compatibility before 1.0.0, Cargo considers 0.x.y to be compatible with 0.x.z , where y ≥ z and x > 0.

Yet the README of the semver crate doesn't meantion that. Neither do some other sections in the Cargo Book, like the section Dependency Resolution, which mentions the deviant behavior regarding 0.x.y versions, but also states that "SemVer" is used (which has a different convention).

I like the way Cargo handles the 0.x.y case, but I feel like it demands more attribution that this is deviant from SemVer.

I also am not sure if there are other differences. The readme linked above states:

Cargo's flavor of Semantic Versioning

But where is this "flavor" (unambiguously) defined?

1 Like

jonhoo spoke about the semver crate (on the Rustacean Station?) a while back, and he mentioned that David Tolnay had made a major overhaul of the crate, including getting into the nitty gritty semantics of versioning, and fixing a bunch of remaining issues. The way I interpreted it was "the best semver definition we have is in the semver crate", but that was merely my interpretation of what a third party said about the work that had been done, so take it with a massive mountain of salt.

With that said, have you checked the semver docs? It's the canonical version number resolver in the rust ecosystem, so if I were interested in the details, that's where I would go.

.. a few minutes later ..

I poked around to see if I could answer your specific questions, and I realized that pre-release versions are witches and should be burned at the stake. :confused:

1 Like

Thanks for looking into it, though. I would like to use pre-release versions for internal testing before I publish a "real" release.

How do other projects handle this? I guess they just use the repository tip?

I'm using version 0.5-rc.1 of Rocket (and I also use a pre-release version of lettre). Perhaps you could look at those crates for some inspiration?

Before today I would never have believed that I would be curious to see what cargo update does once Rocket 0.5 is released.

I will note though that - as mentioned in the github issue you referenced - the prerelease versions are "hidden", so if you go to Rocket's main crates.io page it'll state that the latest release is 0.4.10 (despite the existence of 0.5-rc.1), which is pretty nifty.

I just tried to put rand = "0.7.0-pre.0" as a (new) dependency, and it picked 0.7.3, so at least (empirically) it can update to "released" versions. (Which in a way is counter-intuitive, since I don't think pre-release versions commonly make any guarantees about interface stability).

I guess it should still be possible to write =0.7.0-pre.0 (note the equals sign) or 0.7.0-pre.* to prohibit this. (And not sure if the observed behavior is "stable".)

This topic was automatically closed 90 days after the last reply. We invite you to open a new topic if you have further questions or comments.