Search code examples
rustversioningrust-cargo

Clarify on Cargo's versioning scheme (CHANGELOG vs. Crates.io)


I'm confused about Cargo's versioning scheme: The CHANGELOG has latest released version 1.56 currently (though I've no idea why it also lists releases with a future date), and that's also the version cargo --version reports. That versions seems to follow Rust's version as explained in the README. However, on Crates.io the latest version currently is 0.57.0.

So, how do versions 1.56 and 0.57.0 relate?


Solution

  • In the early days, Rust and Cargo releases weren't necessarily in sync. However, since Rust 1.13 and Cargo 0.14, Rust version 1.x is always paired with Cargo version 0.x+1. Since Rust 1.26, the Cargo binary reports the same version number as Rust by doing math on its package version number.

    The cargo crate published on crates.io is still published with the 0.x+1 version number, because each release is not necessarily backwards compatible with previous releases (the authors do not make any effort to maintain backwards compatibility on the library, but they do maintain compatibility on Cargo.toml and Cargo.lock files), and Cargo considers 0.y and 0.y+1 to be incompatible (this is an extension to Semantic Versioning).

    So, how do versions 1.56 and 0.57.0 relate?

    Rust 1.56.0 was released with Cargo the binary 1.56.0, which uses Cargo the library 0.57.0.

    though I've no idea why it also lists releases with a future date

    The master branch of both Rust and Cargo contain the nightly channel, which is usually 2 versions ahead of the current stable release. Maintainers may add release notes ahead of the actual release so that they don't need to write them all up at once; this means that the release notes for future releases may not be complete. Since releases are made every 6 weeks, release dates for future releases are predictable, so they can write these dates in the release notes with high confidence that it'll be the actual release date.