From 519aaa85d75be56f74bd5a0a946f3be9772da80e Mon Sep 17 00:00:00 2001 From: Aleksey Kladov Date: Sat, 4 Dec 2021 11:01:01 +0300 Subject: [PATCH 1/4] doc: nudge towards simple version requirements --- .../src/reference/specifying-dependencies.md | 54 ++++++++++--------- 1 file changed, 28 insertions(+), 26 deletions(-) diff --git a/src/doc/src/reference/specifying-dependencies.md b/src/doc/src/reference/specifying-dependencies.md index d60d523bd92..a9dab149d79 100644 --- a/src/doc/src/reference/specifying-dependencies.md +++ b/src/doc/src/reference/specifying-dependencies.md @@ -19,35 +19,28 @@ 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. + +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 +48,15 @@ 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 version, +using several requirements 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. From 7aa646d56e404effeabb17a78b861c59aa701477 Mon Sep 17 00:00:00 2001 From: Aleksey Kladov Date: Sat, 4 Dec 2021 19:02:58 +0300 Subject: [PATCH 2/4] Update src/doc/src/reference/specifying-dependencies.md Co-authored-by: Weihang Lo --- src/doc/src/reference/specifying-dependencies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/src/reference/specifying-dependencies.md b/src/doc/src/reference/specifying-dependencies.md index a9dab149d79..b532251beb1 100644 --- a/src/doc/src/reference/specifying-dependencies.md +++ b/src/doc/src/reference/specifying-dependencies.md @@ -25,7 +25,7 @@ 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`, +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. From 7039064d5b62aecbeb2e671f61ed6bef3dd8f31d Mon Sep 17 00:00:00 2001 From: Aleksey Kladov Date: Sat, 4 Dec 2021 11:01:01 +0300 Subject: [PATCH 3/4] doc: nudge towards simple version requirements --- src/doc/src/reference/specifying-dependencies.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/src/doc/src/reference/specifying-dependencies.md b/src/doc/src/reference/specifying-dependencies.md index b532251beb1..2668fed215f 100644 --- a/src/doc/src/reference/specifying-dependencies.md +++ b/src/doc/src/reference/specifying-dependencies.md @@ -48,9 +48,8 @@ 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 version, -using several requirements operators, though it shouldn't be necessary most of -the time. +It is possible to further tweak the logic for selecting compatible version using +special operators, though it shouldn't be necessary most of the time. ### Caret requirements From ec3909e25431e4f64b31e254d66652fd8b4f6939 Mon Sep 17 00:00:00 2001 From: Aleksey Kladov Date: Sun, 5 Dec 2021 14:36:07 +0300 Subject: [PATCH 4/4] doc: fix some stale URLs --- src/doc/src/guide/dependencies.md | 4 ++-- src/doc/src/reference/registries.md | 4 ++-- src/doc/src/reference/specifying-dependencies.md | 8 +++++--- 3 files changed, 9 insertions(+), 7 deletions(-) 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 2668fed215f..bfdadc7efc8 100644 --- a/src/doc/src/reference/specifying-dependencies.md +++ b/src/doc/src/reference/specifying-dependencies.md @@ -21,7 +21,7 @@ time = "0.1.12" 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 +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 @@ -29,6 +29,8 @@ 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: @@ -48,8 +50,8 @@ 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 version using -special operators, though it shouldn't be necessary most of the time. +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