Skip to content

Commit 519aaa8

Browse files
committed
doc: nudge towards simple version requirements
1 parent 7f08ace commit 519aaa8

File tree

1 file changed

+28
-26
lines changed

1 file changed

+28
-26
lines changed

src/doc/src/reference/specifying-dependencies.md

Lines changed: 28 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -19,42 +19,44 @@ guide](../guide/index.md), we specified a dependency on the `time` crate:
1919
time = "0.1.12"
2020
```
2121

22-
The string `"0.1.12"` is a [semver] version requirement. Since this
23-
string does not have any operators in it, it is interpreted the same way as
24-
if we had specified `"^0.1.12"`, which is called a caret requirement.
25-
26-
[semver]: https://github.com/steveklabnik/semver#requirements
27-
28-
### Caret requirements
29-
30-
**Caret requirements** allow SemVer compatible updates to a specified version.
31-
An update is allowed if the new version number does not modify the left-most
32-
non-zero digit in the major, minor, patch grouping. In this case, if we ran
33-
`cargo update -p time`, cargo should update us to version `0.1.13` if it is the
34-
latest `0.1.z` release, but would not update us to `0.2.0`. If instead we had
35-
specified the version string as `^1.0`, cargo should update to `1.1` if it is
36-
the latest `1.y` release, but not `2.0`. The version `0.0.x` is not considered
37-
compatible with any other version.
38-
39-
Here are some more examples of caret requirements and the versions that would
22+
The string `"0.1.12"` is a version requirement. Although it looks like a
23+
specific *version* of the `time` crate, it actually specifies a *range* of
24+
versions and allows SemVer compatible updates. An update is allowed if the new
25+
version number does not modify the left-most non-zero digit in the major, minor,
26+
patch grouping. In this case, if we ran `cargo update -p time`, cargo should
27+
update us to version `0.1.13` if it is the latest `0.1.z` release, but would not
28+
update us to `0.2.0`. If instead we had specified the version string as `^1.0`,
29+
cargo should update to `1.1` if it is the latest `1.y` release, but not `2.0`.
30+
The version `0.0.x` is not considered compatible with any other version.
31+
32+
Here are some more examples of version requirements and the versions that would
4033
be allowed with them:
4134

4235
```notrust
43-
^1.2.3 := >=1.2.3, <2.0.0
44-
^1.2 := >=1.2.0, <2.0.0
45-
^1 := >=1.0.0, <2.0.0
46-
^0.2.3 := >=0.2.3, <0.3.0
47-
^0.2 := >=0.2.0, <0.3.0
48-
^0.0.3 := >=0.0.3, <0.0.4
49-
^0.0 := >=0.0.0, <0.1.0
50-
^0 := >=0.0.0, <1.0.0
36+
1.2.3 := >=1.2.3, <2.0.0
37+
1.2 := >=1.2.0, <2.0.0
38+
1 := >=1.0.0, <2.0.0
39+
0.2.3 := >=0.2.3, <0.3.0
40+
0.2 := >=0.2.0, <0.3.0
41+
0.0.3 := >=0.0.3, <0.0.4
42+
0.0 := >=0.0.0, <0.1.0
43+
0 := >=0.0.0, <1.0.0
5144
```
5245

5346
This compatibility convention is different from SemVer in the way it treats
5447
versions before 1.0.0. While SemVer says there is no compatibility before
5548
1.0.0, Cargo considers `0.x.y` to be compatible with `0.x.z`, where `y ≥ z`
5649
and `x > 0`.
5750

51+
It is possible to further tweak the logic for selecting compatible version,
52+
using several requirements operators, though it shouldn't be necessary most of
53+
the time.
54+
55+
### Caret requirements
56+
57+
**Caret requirements** are an alternative syntax for the default strategy,
58+
`^1.2.3` is exactly equivalent to `1.2.3`.
59+
5860
### Tilde requirements
5961

6062
**Tilde requirements** specify a minimal version with some ability to update.

0 commit comments

Comments
 (0)