doc: nudge towards simple version requirements

[matklad]

Cargo is very ingeniously designed such that the simplest thing you can do when sepcifying a dependency, time = "1.2.3", is also the best thing you can do. However, new Rust folks often overthink this, and use more verbose syntaxes, which at best is unnecessary, and and at worst creates pains downstream. For example, https://github.com/elastic/elasticsearch-rs/blob/master/elasticsearch/Cargo.toml contains a mistrue of default, ~ and ^ requirements, which lets the reader wondering what's going on.

Let's try to help the situation by focusing on default requirements in the docs

[rust-highfive]

r? @Eh2406

(rust-highfive has picked a reviewer for you, use r? to override)

[matklad]

This link is now dead, and the new docs actually refer to this document to explain how requirements work 🤣

[ehuss]

Thanks, this looks good!

Would you mind making a few other minor updates related to this?

• Update the link to semver here in the dependencies page.
• Update the link to semver here in the registries page.
• Add a link somewhere on the specifying-dependencies.md page to somewhere that explains what SemVer is. Nothing really defines what it is, and if you don't already know what it is, I think it can be a little confusing.

There are a few places where these can link. I'll leave it up to you to decide, but some options are:

• https://semver.org/
• https://doc.rust-lang.org/cargo/reference/resolver.html#semver-compatibility — This explains what SemVer is (and links to semver.org), but it was intended more as a reference than an introduction to new users.
• https://doc.rust-lang.org/cargo/reference/semver.html — This doesn't directly explain what SemVer is, so maybe not a good choice.

[matklad]

Updated and also filed #10169 for the possible follow up. It seems that the core problem here is that there's simply isn't an official spec for requirements.

[ehuss]

Thanks!

@bors r+

[bors]

📌 Commit ec3909e has been approved by ehuss

[bors]

⌛ Testing commit ec3909e with merge f9089fc...

[bors]

☀️ Test successful - checks-actions
Approved by: ehuss
Pushing f9089fc to master...