subtle documentation ambiguity

[mcandre]

Problem

The Cargo Book says:

Caret requirements are an alternative syntax for the default strategy, ^1.2.3 is exactly equivalent to 1.2.3.

This phrasing has an unfortunate interpretation for Rust newbies, who may take the statement to mean that caret means the exact version identifier.

A very careful reading reveals that caret is merely the default semantic, but is not exactly equivalent to any fixed version. Some users may get tripped up by this ambiguity.

Possible Solution(s)

We can help the reader to disambiguate Cargo syntax and semantics. For example, adjust the section to say something like:

The caret prefix is also the default version resolution strategy; it may be omitted. Both ^1.2.3 and 1.2.3 match the latest available, Cargo SemVer compatible release that Cargo can find.

[weihanglo]

Thanks for the report. If I recall correctly, caret ^ is really only an alternative syntax for “SemVer compatible” version requirements. We encourage people to use “1.2.3” instead of “^1.2.3” at syntax level. See #10158.

That being said, I feel like we missed a clear mention of “default strategy” in the paragraph above, as well as encourage people to avoid prefixes unless really needed. We can perhaps disambiguate the sentence with something like

Caret requirements are an alternative syntax for the default strategy. For instance, log = "^1.2.3" is exactly equivalent to log = "1.2.3", which allows SemVer compatible updates.

[ehuss]

I'm wondering if the confusion is also rooted with the use of the word "exactly"? Maybe phrasing it as: `log = "^1.2.3"` means the same thing as `log = "1.2.3", which allows …` could help?