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 |
| 63 version is considered higher priority than any unstable version. The above |
| 64 versions, in priority order, are: |
| 65 |
| 66 * `1.2.0-alpha` |
| 67 * `1.3.0-experimental` |
| 68 * `1.0.0` |
| 69 * `1.2.0` |
| 70 |
| 71 This ensures that users only end up with an unstable version when there are |
| 72 no alternatives. Usually this means they've picked a constraint that |
| 73 specifically selects that unstable version -- they've deliberately opted |
| 74 into it. |
| 75 |
| 76 [pub]: http://pub.dartlang.org/ |
| 77 [semver]: http://semver.org/ |
OLD | NEW |