cargo guide: guidance around selecting the version of a dependency?

[kevinushey]

Problem

In the cargo guide, the page on dependencies (https://doc.rust-lang.org/cargo/guide/dependencies.html) describes how one can add specific versions of a couple dependencies, e.g. by editing Cargo.toml:

[package]
name = "hello_world"
version = "0.1.0"
edition = "2021"

[dependencies]
time = "0.1.12"
regex = "0.1.41"

and then links to external documentation regarding SemVer and how other / newer versions of packages could be requested.

However, the documentation doesn't provide any specific guidance around how one should normally choose the versions of their dependencies. Is there any existing convention in the community? For example:

• Prefer using the latest major release?
• Look at the documentation on crates.io, and make a choice there?
• Use an external tool to add dependencies to the project?

It might also be worth documenting the use of cargo add, once #2179 becomes part of stable.

It would also be nice if the crate versions chosen in this documentation matched a more current version (regex is currently 1.5.5, based on https://crates.io/crates/regex).

Proposed Solution

• Consider providing some guidance for users on how dependency versioning should be done.
  • In particular, note if there are any consequences for downstream users if you plan to build a rust library?
• Document and describe the use of cargo add?

Notes

No response

[kevinushey]

I also stumbled on a semi-related entry in the FAQ:

https://doc.rust-lang.org/cargo/faq.html#can-libraries-use--as-a-version-for-their-dependencies

which I think implicitly recommends versioning of the form 1.4.* or 1.*.

[epage]

For how precise to be, there was a users thread on that subject.

It might also be worth documenting the use of cargo add, once #2179 becomes part of stable.

In addition to the guide page, we should also consider the reference page. The former can focus more on cargo add but the latter needs to go into all the details and not get distracted too much with cargo add. Both can cross-link to cargo add's documentation page.

We've also talked about getting crates.io to be updated to reference cargo add.

[harrybraviner]

@kevinushey - I agree with you about your interpretation somewhat. That FAQ answer is saying that you may use 1.* or 1.4.* (at least for a package published to crates.io), but it isn't recommending that you do so.

If the package is following semantic versioning, the constraint I would like is "MAJOR number must be exactly X, MINOR number and PATCH must be at least Y.Z". But I don't know if I can enforce that in Cargo?

The other question I don't know the answer to, but it seems relevant, is this: Suppose my package A depends on packaged B and C. And B and C both depend on package D. Is my build of package A faster if B and C depend on the same version of D?

Sorry I'm not adding answers here - I'm just flagging some ways that I, as a relatively inexperienced Cargo user, also get confused.

[Eh2406]

"MAJOR number must be exactly X, MINOR number and PATCH must be at least Y.Z". But I don't know if I can enforce that in Cargo?

You are looking for the ^ requirement, witch is also the one you get if you do not use a symbol. ^X.Y.Z or X.Y.Z (If X is 0, then it is MINOR number must be exactly Y, PATCH must be at least Z")

Is my build of package A faster if B and C depend on the same version of D?

Yes, Clean builds will generally be faster when things unify. But, developers want the latest changes from there deps and want a way to upgrade. As a compromise, Cargo will try to get the largess version for each dep (even if that means having D 1.0.0 and D 2.0.0 in the tree), but will only select one semver compatible version in each category (so a requirement ^1.0 may resolve to 1.5 even if 1.9 is available so that it can unify with some other requirement >=1.0, <=1.5).

[matschaffer]

This might deserve it's own issue, but I found my way here wishing that cargo add could resolve the version for me, but leave out the patch version. Maybe something like this?

cargo add (crate) --minor

I love that cargo add can go find the latest version for me, I just don't want it to lock all the way to the patch version.

As a workaround I run add then remove the patch version from my Cargo.toml manually.

[epage]

People have requested options for controlling the precision but I've generally pushed back

• We want to keep the scope narrow so the --help is not overwhelming for new users and they run into paralysis from choice
• We want to keep the scope for cargo add narrow to not overwhelm the cargo team
• Workarounds exist, either by manually editing or by manually adding
• We prefer full precision as its the safest minimal version of the dependency

However, to support people who do customize their precision, cargo upgrade preserves the existing precision.