Version Constraints and the Lock File
The http line in Sprout's pubspec.yaml says ^1.2.0, yet your machine is using version 1.2.2. A teammate's might pick something else next month. To reason about that, you need to read two things: the constraint you wrote, and the lock file pub wrote for you.
The rule
The caret allows everything up to the next breaking version; the lock file pins one.
Dart packages use semantic versioning: major.minor.patch.
- Patch (1.2.2): bug fixes.
- Minor (1.3.0): new features, nothing removed.
- Major (2.0.0): may break existing code.
A caret constraint accepts any version that should be compatible:
| Constraint | Allows | Stops before |
|---|---|---|
^1.2.0 |
1.2.0, 1.2.9, 1.9.4 | 2.0.0 |
^0.4.1 |
0.4.1, 0.4.7 | 0.5.0 |
For packages still below 1.0, the minor number plays the role of the breaking one, so the caret stops at the next minor.
Other forms exist, such as an exact 1.2.0 or a range '>=1.2.0 <1.5.0', but the caret is the normal choice and what pub add writes.
pubspec.lock records the single version pub actually chose for every package, including the packages your packages depend on:
http:
dependency: "direct main"
source: hosted
version: "1.2.2"flutter pub get reuses those locked versions. Only flutter pub upgrade (or changing a constraint) chooses new ones.
The shortcut
To read a caret, bump the major number; if the major is 0, bump the minor instead. That is the ceiling.
^1.2.0The major is 1, so bump it: ceiling 2.0.0. Allowed: 1.2.0 up to, not including, 2.0.0.
The trap is expecting flutter pub upgrade to jump to a new major version. It stays inside your constraints; crossing a major is a deliberate edit.
Drills
Answer fast — trust the rule.
Which version does ^1.2.0 allow?
What is the ceiling of ^0.4.1?
What does pubspec.lock record?
http: ^1.2.0 is locked at 1.2.2, and 2.0.0 has just been released. What does flutter pub upgrade do?
In semantic versioning, which change signals that existing code may break?
Remember
- The caret allows everything up to the next breaking version; the lock file pins one.
- Bump the major to get the ceiling; if the major is 0, bump the minor.
- Trap:
upgradenever crosses a major version by itself.