OLD | NEW |
---|---|
(Empty) | |
1 Handles version numbers and version constraints in the same way that [pub][] | |
2 does. The semantics here very closely follow the [Semantic Versioning][semver] | |
3 spec. It differs from semver in a few corner cases: | |
4 | |
5 * **Version ordering does take build suffixes into account.** This is unlike | |
6 semver 2.0.0 but like earlier versions of semver. Version `1.2.3+1` is | |
7 considered a lower number than `1.2.3+2`. | |
8 | |
9 Since a package may have published multiple versions that differ only by | |
10 build suffix, pub still has to pick one of them *somehow*. Semver leaves | |
11 that issue unresolved, so we just say that build numbers are sorted like | |
12 pre-release suffixes. | |
13 | |
14 * **Pre-release versions are excluded from most max ranges.** Let's say a | |
15 user is depending on "foo" with constraint `>=1.0.0 <2.0.0` and that "foo" | |
16 has published these versions: | |
17 | |
18 * `1.0.0` | |
19 * `1.1.0` | |
20 * `1.2.0` | |
21 * `2.0.0-alpha` | |
22 * `2.0.0-beta` | |
23 * `2.0.0` | |
24 * `2.1.0` | |
25 | |
26 Versions `2.0.0` and `2.1.0` are excluded by the constraint since neither | |
27 matches `<2.0.0`. However, since semver specifies that pre-release versions | |
28 are lower than the non-prerelease version (i.e. `2.0.0-beta < 2.0.0`, then | |
29 the `<2.0.0` constraint does technically allow those. | |
30 | |
31 But that's almost never what the user wants. If their package doesn't work | |
32 with foo `2.0.0`, it's certainly not likely to work with experimental, | |
33 unstable versions of `2.0.0`'s API, which is what pre-release versions | |
34 represent. | |
35 | |
36 To handle that, `<` version ranges to not allow pre-release versions of the | |
37 maximum unless the max is itself a pre-release. In other words, a `<2.0.0` | |
38 constraint will prohibit not just `2.0.0` but any pre-release of `2.0.0`. | |
39 However, `<2.0.0-beta` will exclude `2.0.0-beta` but allow `2.0.0-alpha`. | |
40 | |
41 * **Pre-release versions are avoided when possible.** The above case | |
42 handles pre-release versions at the top of the range, but what about in | |
43 the middle? What if "foo" has these versions: | |
44 | |
45 * `1.0.0` | |
46 * `1.2.0-alpha` | |
47 * `1.2.0` | |
48 * `1.3.0-experimental` | |
49 | |
50 When a number of versions are valid, pub chooses the best one where "best" | |
51 usually means "highest numbered". That follows the user's intuition that, | |
52 all else being equal, they want the latest and greatest. Here, that would | |
53 mean `1.3.0-experimental`. However, most users don't want to use unstable | |
54 versions of their dependencies. | |
55 | |
56 We want pre-releases to be explicitly opt-in so that package consumers | |
57 don't get unpleasant surprises and so that package maintainers are free to | |
58 put out pre-releases and get feedback without dragging all of their users | |
59 onto the bleeding edge. | |
60 | |
61 To accommodate that, when pub is choosing a version, it uses *priority* | |
62 order which is different from strict comparison ordering. Any stable version is considered higher priority than any unstable version. The above versions, in priority order, are: | |
nweiz
2014/09/25 22:52:02
Long line.
Bob Nystrom
2014/09/26 19:41:07
Done.
| |
63 | |
64 * `1.2.0-alpha` | |
65 * `1.3.0-experimental` | |
66 * `1.0.0` | |
67 * `1.2.0` | |
68 | |
69 This ensures that users only end up with an unstable version when there are | |
70 no alternatives. Usually this means they've picked a constraint that | |
71 specifically selects that unstable version -- they've deliberately opted in | |
72 to it. | |
nweiz
2014/09/25 22:52:02
Nit: "in to" -> "into"
Bob Nystrom
2014/09/26 19:41:07
Done.
| |
73 | |
74 [pub]: http://pub.dartlang.org/ | |
75 [semver]: http://semver.org/ | |
OLD | NEW |