search

rust-lang / cargo

The Rust package manager
https://doc.rust-lang.org/cargo
Apache License 2.0
12.76k stars 2.42k forks source link

Properly specify syntax and semantics for SemVer version requrenments #10169

Open matklad opened 2 years ago

matklad commented 2 years ago

Problem

Problem 1: there's no canonical spec for requirements. Specifically, what can be on the rhs in time = "0.1". Notably, this is not part of the semver spec. This is logic specific to Cargo (although it is similar to npm's one) and should be documented by us.

Problem 2: although all the info is documented in the current docs, I feel the info is spread across several pages in less than optimal ways.

Proposed Solution

Create SemVer Requrenments document in the reference section of the book, and move https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#specifying-dependencies-from-cratesio section there. The doc should describe syntax and semantics of SemVerReq, but shouldn't talk about path dependencies or alternative registries

In the current specifying-dependencies page, just link the new page. This is ok for reference docs.

In the guide section, update the examples to use past 1.0 crates. Say something along the lines of

time = "1.2.0" is a semver requrenment, and would allow any SemVer compatible version. For example, 1.3.2 would be allowed, but 1.1.9 or 2.0.0 would not. See NEW PAGE LINK for details. It is also possible to depend on local crates or github repositories, see OLD PAGE LINK for details

Link the new page from semver crate's docs as well

Notes

No response

ehuss commented 2 years ago

Just FYI, there is some movement to officially document it here. I'm not sure if that will come to fruition, though. I think it would be good to have our own more explicit docs.