doc: semver behaviour of cargo confusing in guessing game

[ecksun]

I just started reading about the guessing game in the rust book and thought I should share my experiences.

When being introduced to dependencies in cargo the version specification given is:

[dependencies]

rand="0.3.0"

Followed by this text:

So, we told Cargo we wanted any 0.3.x version of rand...

This was very confusing for me coming from using semver with npm, I expected 0.3.0 to match exactly and it took me a while to understand why that was not the case.

Apparently npm's default behaviour is to match an exact version while cargo's is to use a careted version.

It is documented on http://doc.crates.io/crates-io.html that cargo defaults to use careted versions:

Caret requirements allow SemVer compatible updates to a specified version, 0.1 and 0.2 are not considered compatible, but 1.0 and 1.1 are for example. If no operator is specified, this is the default requirement (e.g. 1.3 is the same as ^1.3).

Which differs from npm, from https://docs.npmjs.com/misc/semver :

= Equal. If no operator is specified, then equality is assumed, so this operator is optional, but MAY be included.

I would like to offer two suggestions:

Explain in the guessing game how we told Cargo we wanted a 0.3.x version, currently this is just a statement (So, we told Cargo we wanted ...) without explanation.

Make it more clear how cargo and npm differ with regards to semver, especially considering npm is linked to directly in the documentation.