Skip to content

Commit 8e698ea

Browse files
mosuemmosuem
committed
Merge package:pub_semver into the tools monorepo
2 parents faf2b86 + 7cb7ee0 commit 8e698ea

21 files changed

+4121
-0
lines changed

‎pkgs/pub_semver/.github/dependabot.yaml

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Dependabot configuration file.
2+
version: 2
3+
4+
updates:
5+
- package-ecosystem: github-actions
6+
directory: /
7+
schedule:
8+
interval: monthly
9+
labels:
10+
- autosubmit
11+
groups:
12+
github-actions:
13+
patterns:
14+
- "*"

‎pkgs/pub_semver/.github/workflows/test-package.yml

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
name: Dart CI
2+
3+
on:
4+
# Run on PRs and pushes to the default branch.
5+
push:
6+
branches: [ master ]
7+
pull_request:
8+
branches: [ master ]
9+
schedule:
10+
- cron: "0 0 * * 0"
11+
12+
env:
13+
PUB_ENVIRONMENT: bot.github
14+
15+
jobs:
16+
# Check code formatting and static analysis on a single OS (linux)
17+
# against Dart dev.
18+
analyze:
19+
runs-on: ubuntu-latest
20+
strategy:
21+
fail-fast: false
22+
matrix:
23+
sdk: [dev]
24+
steps:
25+
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
26+
- uses: dart-lang/setup-dart@e630b99d28a3b71860378cafdc2a067c71107f94
27+
with:
28+
sdk: ${{ matrix.sdk }}
29+
- id: install
30+
name: Install dependencies
31+
run: dart pub get
32+
- name: Check formatting
33+
run: dart format --output=none --set-exit-if-changed .
34+
if: always() && steps.install.outcome == 'success'
35+
- name: Analyze code
36+
run: dart analyze --fatal-infos
37+
if: always() && steps.install.outcome == 'success'
38+
39+
# Run tests on a matrix consisting of two dimensions:
40+
# 1. OS: ubuntu-latest, (macos-latest, windows-latest)
41+
# 2. release channel: dev
42+
test:
43+
needs: analyze
44+
runs-on: ${{ matrix.os }}
45+
strategy:
46+
fail-fast: false
47+
matrix:
48+
# Add macos-latest and/or windows-latest if relevant for this package.
49+
os: [ubuntu-latest]
50+
sdk: [3.4, dev]
51+
steps:
52+
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
53+
- uses: dart-lang/setup-dart@e630b99d28a3b71860378cafdc2a067c71107f94
54+
with:
55+
sdk: ${{ matrix.sdk }}
56+
- id: install
57+
name: Install dependencies
58+
run: dart pub get
59+
- name: Run VM tests
60+
run: dart test --platform vm
61+
if: always() && steps.install.outcome == 'success'
62+
- name: Run Chrome tests
63+
run: dart test --platform chrome --compiler dart2js,dart2wasm
64+
if: always() && steps.install.outcome == 'success'

‎pkgs/pub_semver/.gitignore

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
.dart_tool/
2+
.packages
3+
pubspec.lock

‎pkgs/pub_semver/CHANGELOG.md

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
## 2.1.5-wip
2+
3+
- Require Dart `3.4.0`.
4+
5+
## 2.1.4
6+
7+
- Added topics to `pubspec.yaml`.
8+
9+
## 2.1.3
10+
11+
- Add type parameters to the signatures of the `Version.preRelease` and
12+
`Version.build` fields (`List` ==> `List<Object>`).
13+
[#74](https://github.com/dart-lang/pub_semver/pull/74).
14+
- Require Dart 2.17.
15+
16+
## 2.1.2
17+
18+
- Add markdown badges to the readme.
19+
20+
## 2.1.1
21+
22+
- Fixed the version parsing pattern to only accept dots between version
23+
components.
24+
25+
## 2.1.0
26+
27+
- Added `Version.canonicalizedVersion` to help scrub leading zeros and highlight
28+
that `Version.toString()` preserves leading zeros.
29+
- Annotated `Version` with `@sealed` to discourage users from implementing the
30+
interface.
31+
32+
## 2.0.0
33+
34+
- Stable null safety release.
35+
- `Version.primary` now throws `StateError` if the `versions` argument is empty.
36+
37+
## 1.4.4
38+
39+
- Fix a bug of `VersionRange.union` where ranges bounded at infinity would get
40+
combined wrongly.
41+
42+
# 1.4.3
43+
44+
- Update Dart SDK constraint to `>=2.0.0 <3.0.0`.
45+
- Update `package:collection` constraint to `^1.0.0`.
46+
47+
## 1.4.2
48+
49+
* Set max SDK version to `<3.0.0`.
50+
51+
## 1.4.1
52+
53+
* Fix a bug where there upper bound of a version range with a build identifier
54+
could accidentally be rewritten.
55+
56+
## 1.4.0
57+
58+
* Add a `Version.firstPreRelease` getter that returns the first possible
59+
pre-release of a version.
60+
61+
* Add a `Version.isFirstPreRelease` getter that returns whether a version is the
62+
first possible pre-release.
63+
64+
* `new VersionRange()` with an exclusive maximum now replaces the maximum with
65+
its first pre-release version. This matches the existing semantics, where an
66+
exclusive maximum would exclude pre-release versions of that maximum.
67+
68+
Explicitly representing this by changing the maximum version ensures that all
69+
operations behave correctly with respect to the special pre-release semantics.
70+
In particular, it fixes bugs where, for example,
71+
`(>=1.0.0 <2.0.0-dev).union(>=2.0.0-dev <2.0.0)` and
72+
`(>=1.0.0 <3.0.0).difference(^1.0.0)` wouldn't include `2.0.0-dev`.
73+
74+
* Add an `alwaysIncludeMaxPreRelease` parameter to `new VersionRange()`, which
75+
disables the replacement described above and allows users to create ranges
76+
that do include the pre-release versions of an exclusive max version.
77+
78+
## 1.3.7
79+
80+
* Fix more bugs with `VersionRange.intersect()`, `VersionRange.difference()`,
81+
and `VersionRange.union()` involving version ranges with pre-release maximums.
82+
83+
## 1.3.6
84+
85+
* Fix a bug where constraints that only allowed pre-release versions would be
86+
parsed as empty constraints.
87+
88+
## 1.3.5
89+
90+
* Fix a bug where `VersionRange.intersect()` would return incorrect results for
91+
pre-release versions with the same base version number as release versions.
92+
93+
## 1.3.4
94+
95+
* Fix a bug where `VersionRange.allowsAll()`, `VersionRange.allowsAny()`, and
96+
`VersionRange.difference()` would return incorrect results for pre-release
97+
versions with the same base version number as release versions.
98+
99+
## 1.3.3
100+
101+
* Fix a bug where `VersionRange.difference()` with a union constraint that
102+
covered the entire range would crash.
103+
104+
## 1.3.2
105+
106+
* Fix a checked-mode error in `VersionRange.difference()`.
107+
108+
## 1.3.1
109+
110+
* Fix a new strong mode error.
111+
112+
## 1.3.0
113+
114+
* Make the `VersionUnion` class public. This was previously used internally to
115+
implement `new VersionConstraint.unionOf()` and `VersionConstraint.union()`.
116+
Now it's public so you can use it too.
117+
118+
* Added `VersionConstraint.difference()`. This returns a constraint matching all
119+
versions matched by one constraint but not another.
120+
121+
* Make `VersionRange` implement `Comparable<VersionRange>`. Ranges are ordered
122+
first by lower bound, then by upper bound.
123+
124+
## 1.2.4
125+
126+
* Fix all remaining strong mode warnings.
127+
128+
## 1.2.3
129+
130+
* Addressed three strong mode warnings.
131+
132+
## 1.2.2
133+
134+
* Make the package analyze under strong mode and compile with the DDC (Dart Dev
135+
Compiler). Fix two issues with a private subclass of `VersionConstraint`
136+
having different types for overridden methods.
137+
138+
## 1.2.1
139+
140+
* Allow version ranges like `>=1.2.3-dev.1 <1.2.3` to match pre-release versions
141+
of `1.2.3`. Previously, these didn't match, since the pre-release versions had
142+
the same major, minor, and patch numbers as the max; now an exception has been
143+
added if they also have the same major, minor, and patch numbers as the min
144+
*and* the min is also a pre-release version.
145+
146+
## 1.2.0
147+
148+
* Add a `VersionConstraint.union()` method and a `new
149+
VersionConstraint.unionOf()` constructor. These each return a constraint that
150+
matches multiple existing constraints.
151+
152+
* Add a `VersionConstraint.allowsAll()` method, which returns whether one
153+
constraint is a superset of another.
154+
155+
* Add a `VersionConstraint.allowsAny()` method, which returns whether one
156+
constraint overlaps another.
157+
158+
* `Version` now implements `VersionRange`.
159+
160+
## 1.1.0
161+
162+
* Add support for the `^` operator for compatible versions according to pub's
163+
notion of compatibility. `^1.2.3` is equivalent to `>=1.2.3 <2.0.0`; `^0.1.2`
164+
is equivalent to `>=0.1.2 <0.2.0`.
165+
166+
* Add `Version.nextBreaking`, which returns the next version that introduces
167+
breaking changes after a given version.
168+
169+
* Add `new VersionConstraint.compatibleWith()`, which returns a range covering
170+
all versions compatible with a given version.
171+
172+
* Add a custom `VersionRange.hashCode` to make it properly hashable.
173+
174+
## 1.0.0
175+
176+
* Initial release.

‎pkgs/pub_semver/LICENSE

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
Copyright 2014, the Dart project authors.
2+
3+
Redistribution and use in source and binary forms, with or without
4+
modification, are permitted provided that the following conditions are
5+
met:
6+
7+
* Redistributions of source code must retain the above copyright
8+
notice, this list of conditions and the following disclaimer.
9+
* Redistributions in binary form must reproduce the above
10+
copyright notice, this list of conditions and the following
11+
disclaimer in the documentation and/or other materials provided
12+
with the distribution.
13+
* Neither the name of Google LLC nor the names of its
14+
contributors may be used to endorse or promote products derived
15+
from this software without specific prior written permission.
16+
17+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
18+
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
19+
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
20+
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
21+
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
22+
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
23+
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
24+
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
25+
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
26+
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
27+
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

‎pkgs/pub_semver/README.md

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
[![Dart CI](https://github.com/dart-lang/pub_semver/actions/workflows/test-package.yml/badge.svg)](https://github.com/dart-lang/pub_semver/actions/workflows/test-package.yml)
2+
[![Pub](https://img.shields.io/pub/v/pub_semver.svg)](https://pub.dev/packages/pub_semver)
3+
[![package publisher](https://img.shields.io/pub/publisher/pub_semver.svg)](https://pub.dev/packages/pub_semver/publisher)
4+
5+
Handles version numbers and version constraints in the same way that [pub][]
6+
does.
7+
8+
## Semantics
9+
10+
The semantics here very closely follow the
11+
[Semantic Versioning spec version 2.0.0-rc.1][semver]. It differs from semver
12+
in a few corner cases:
13+
14+
* **Version ordering does take build suffixes into account.** This is unlike
15+
semver 2.0.0 but like earlier versions of semver. Version `1.2.3+1` is
16+
considered a lower number than `1.2.3+2`.
17+
18+
Since a package may have published multiple versions that differ only by
19+
build suffix, pub still has to pick one of them *somehow*. Semver leaves
20+
that issue unresolved, so we just say that build numbers are sorted like
21+
pre-release suffixes.
22+
23+
* **Pre-release versions are excluded from most max ranges.** Let's say a
24+
user is depending on "foo" with constraint `>=1.0.0 <2.0.0` and that "foo"
25+
has published these versions:
26+
27+
* `1.0.0`
28+
* `1.1.0`
29+
* `1.2.0`
30+
* `2.0.0-alpha`
31+
* `2.0.0-beta`
32+
* `2.0.0`
33+
* `2.1.0`
34+
35+
Versions `2.0.0` and `2.1.0` are excluded by the constraint since neither
36+
matches `<2.0.0`. However, since semver specifies that pre-release versions
37+
are lower than the non-prerelease version (i.e. `2.0.0-beta < 2.0.0`, then
38+
the `<2.0.0` constraint does technically allow those.
39+
40+
But that's almost never what the user wants. If their package doesn't work
41+
with foo `2.0.0`, it's certainly not likely to work with experimental,
42+
unstable versions of `2.0.0`'s API, which is what pre-release versions
43+
represent.
44+
45+
To handle that, `<` version ranges don't allow pre-release versions of the
46+
maximum unless the max is itself a pre-release, or the min is a pre-release
47+
of the same version. In other words, a `<2.0.0` constraint will prohibit not
48+
just `2.0.0` but any pre-release of `2.0.0`. However, `<2.0.0-beta` will
49+
exclude `2.0.0-beta` but allow `2.0.0-alpha`. Likewise, `>2.0.0-alpha
50+
<2.0.0` will exclude `2.0.0-alpha` but allow `2.0.0-beta`.
51+
52+
* **Pre-release versions are avoided when possible.** The above case
53+
handles pre-release versions at the top of the range, but what about in
54+
the middle? What if "foo" has these versions:
55+
56+
* `1.0.0`
57+
* `1.2.0-alpha`
58+
* `1.2.0`
59+
* `1.3.0-experimental`
60+
61+
When a number of versions are valid, pub chooses the best one where "best"
62+
usually means "highest numbered". That follows the user's intuition that,
63+
all else being equal, they want the latest and greatest. Here, that would
64+
mean `1.3.0-experimental`. However, most users don't want to use unstable
65+
versions of their dependencies.
66+
67+
We want pre-releases to be explicitly opt-in so that package consumers
68+
don't get unpleasant surprises and so that package maintainers are free to
69+
put out pre-releases and get feedback without dragging all of their users
70+
onto the bleeding edge.
71+
72+
To accommodate that, when pub is choosing a version, it uses *priority*
73+
order which is different from strict comparison ordering. Any stable
74+
version is considered higher priority than any unstable version. The above
75+
versions, in priority order, are:
76+
77+
* `1.2.0-alpha`
78+
* `1.3.0-experimental`
79+
* `1.0.0`
80+
* `1.2.0`
81+
82+
This ensures that users only end up with an unstable version when there are
83+
no alternatives. Usually this means they've picked a constraint that
84+
specifically selects that unstable version -- they've deliberately opted
85+
into it.
86+
87+
* **There is a notion of compatibility between pre-1.0.0 versions.** Semver
88+
deems all pre-1.0.0 versions to be incompatible. This means that the only
89+
way to ensure compatibility when depending on a pre-1.0.0 package is to
90+
pin the dependency to an exact version. Pinned version constraints prevent
91+
automatic patch and pre-release updates. To avoid this situation, pub
92+
defines the "next breaking" version as the version which increments the
93+
major version if it's greater than zero, and the minor version otherwise,
94+
resets subsequent digits to zero, and strips any pre-release or build
95+
suffix. For example, here are some versions along with their next breaking
96+
ones:
97+
98+
`0.0.3` -> `0.1.0`
99+
`0.7.2-alpha` -> `0.8.0`
100+
`1.2.3` -> `2.0.0`
101+
102+
To make use of this, pub defines a "^" operator which yields a version
103+
constraint greater than or equal to a given version, but less than its next
104+
breaking one.
105+
106+
[pub]: https://pub.dev
107+
[semver]: https://semver.org/spec/v2.0.0-rc.1.html

0 commit comments

Comments
 (0)