diff --git a/src/doc/src/guide/dependencies.md b/src/doc/src/guide/dependencies.md index a47f747e4d6..94419f15b7a 100644 --- a/src/doc/src/guide/dependencies.md +++ b/src/doc/src/guide/dependencies.md @@ -20,11 +20,11 @@ use. This example adds a dependency of the `time` crate: time = "0.1.12" ``` -The version string is a [semver] version requirement. The [specifying +The version string is a [SemVer] version requirement. The [specifying dependencies](../reference/specifying-dependencies.md) docs have more information about the options you have here. -[semver]: https://github.com/steveklabnik/semver#requirements +[SemVer]: https://semver.org If we also wanted to add a dependency on the `regex` crate, we would not need to add `[dependencies]` for each crate listed. Here's what your whole diff --git a/src/doc/src/reference/registries.md b/src/doc/src/reference/registries.md index 96eb15e082c..ef23caeee1f 100644 --- a/src/doc/src/reference/registries.md +++ b/src/doc/src/reference/registries.md @@ -222,9 +222,9 @@ explaining the format of the entry. // this is the new name. The original package name is stored in // the `package` field. "name": "rand", - // The semver requirement for this dependency. + // The SemVer requirement for this dependency. // This must be a valid version requirement defined at - // https://github.com/steveklabnik/semver#requirements. + // https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html. "req": "^0.6", // Array of features (as strings) enabled for this dependency. "features": ["i128_support"], diff --git a/src/doc/src/reference/specifying-dependencies.md b/src/doc/src/reference/specifying-dependencies.md index d60d523bd92..bfdadc7efc8 100644 --- a/src/doc/src/reference/specifying-dependencies.md +++ b/src/doc/src/reference/specifying-dependencies.md @@ -19,35 +19,30 @@ guide](../guide/index.md), we specified a dependency on the `time` crate: time = "0.1.12" ``` -The string `"0.1.12"` is a [semver] version requirement. Since this -string does not have any operators in it, it is interpreted the same way as -if we had specified `"^0.1.12"`, which is called a caret requirement. - -[semver]: https://github.com/steveklabnik/semver#requirements - -### Caret requirements - -**Caret requirements** allow SemVer compatible updates to a specified version. -An update is allowed if the new version number does not modify the left-most -non-zero digit in the major, minor, patch grouping. In this case, if we ran -`cargo update -p time`, cargo should update us to version `0.1.13` if it is the -latest `0.1.z` release, but would not update us to `0.2.0`. If instead we had -specified the version string as `^1.0`, cargo should update to `1.1` if it is -the latest `1.y` release, but not `2.0`. The version `0.0.x` is not considered -compatible with any other version. - -Here are some more examples of caret requirements and the versions that would +The string `"0.1.12"` is a version requirement. Although it looks like a +specific *version* of the `time` crate, it actually specifies a *range* of +versions and allows [SemVer] compatible updates. An update is allowed if the new +version number does not modify the left-most non-zero digit in the major, minor, +patch grouping. In this case, if we ran `cargo update -p time`, cargo should +update us to version `0.1.13` if it is the latest `0.1.z` release, but would not +update us to `0.2.0`. If instead we had specified the version string as `1.0`, +cargo should update to `1.1` if it is the latest `1.y` release, but not `2.0`. +The version `0.0.x` is not considered compatible with any other version. + +[SemVer]: https://semver.org + +Here are some more examples of version requirements and the versions that would be allowed with them: ```notrust -^1.2.3 := >=1.2.3, <2.0.0 -^1.2 := >=1.2.0, <2.0.0 -^1 := >=1.0.0, <2.0.0 -^0.2.3 := >=0.2.3, <0.3.0 -^0.2 := >=0.2.0, <0.3.0 -^0.0.3 := >=0.0.3, <0.0.4 -^0.0 := >=0.0.0, <0.1.0 -^0 := >=0.0.0, <1.0.0 +1.2.3 := >=1.2.3, <2.0.0 +1.2 := >=1.2.0, <2.0.0 +1 := >=1.0.0, <2.0.0 +0.2.3 := >=0.2.3, <0.3.0 +0.2 := >=0.2.0, <0.3.0 +0.0.3 := >=0.0.3, <0.0.4 +0.0 := >=0.0.0, <0.1.0 +0 := >=0.0.0, <1.0.0 ``` This compatibility convention is different from SemVer in the way it treats @@ -55,6 +50,14 @@ versions before 1.0.0. While SemVer says there is no compatibility before 1.0.0, Cargo considers `0.x.y` to be compatible with `0.x.z`, where `y ≥ z` and `x > 0`. +It is possible to further tweak the logic for selecting compatible versions +using special operators, though it shouldn't be necessary most of the time. + +### Caret requirements + +**Caret requirements** are an alternative syntax for the default strategy, +`^1.2.3` is exactly equivalent to `1.2.3`. + ### Tilde requirements **Tilde requirements** specify a minimal version with some ability to update.