Versioning
Each dependency has a version scheme. It decides how versions sort, which update class a change belongs to, whether a version satisfies a range, and how a range is rewritten.
| Scheme | Used by | Notes |
|---|---|---|
semver |
npm, Cargo, most GitHub sources | npm and Cargo requirements are parsed separately: bare 1.2.3 is exact in npm and compatible in Cargo |
docker |
container images | a numeric prefix plus a variant suffix that never changes (-alpine, -bookworm) |
pep440 |
PEP 621, uv | epochs, pre/dev/post and local versions, ~=, wildcards and exclusions |
poetry |
Poetry | ^ keeps the leftmost nonzero part, ~ allows patches (minors for a bare major), || separates alternatives |
go |
Go modules | canonical v SemVer and pseudo-versions |
hashicorp |
Terraform | =, !=, comparisons, ~> (two- and three-part forms differ) |
maven |
Maven, Gradle | Maven’s ordering: alpha < beta < milestone < rc < snapshot < release < sp; release variants such as -jre are kept |
nuget |
NuGet | SemVer 2 with an optional fourth number; interval ranges like [2.9.0,3.0) |
rubygems |
Bundler | letters make a prerelease (1.0.0.rc1 < 1.0.0), ~> |
composer |
Composer | up to four numbers, alpha < beta < RC < stable < patch, ^, ~, wildcards, hyphen ranges, || |
loose |
mise tools, toolchains | numeric dotted versions with an optional v |
Update classes
Section titled “Update classes”Major, minor and patch follow each scheme’s own components. Cargo counts a
change in the leftmost nonzero component as major, so 0.3 to 0.4 is major,
as Cargo’s compatibility rules say. A Python epoch change is major. Prereleases
are only proposed as release age and channels
describes.
Version policies
Section titled “Version policies”versions decides what happens to the declaration:
exactpins the target. Cargo writes=1.2.3, because a bare version in Cargo allows compatible releases. Python writes==.preserveleaves a range alone while it is still satisfied, and shifts simple caret, tilde and wildcard ranges when it is not (^6.4becomes^7.1).widenextends the range to include the new version, where the syntax can express that (see below), and otherwise behaves aspreserve.
A constraint that cannot be rewritten to allow the new version without guessing
(>=1.0 <2.0 needing 3.0, or a Bundler ">= 1, < 2" needing 2) is not a
failed lookup. The Count found the release; he just will not invent a
declaration for it. The release is reported as a
notice with the reason, listed on the dashboard under
“Newer versions not proposed”, and the dependency’s other updates go ahead.
Under preserve a shifted range keeps the precision it was declared with:
~=2.28 becomes ~=3.1, not ~=3.1.4, and Terraform’s ~> 6.0 becomes
~> 7.1. A specifier that needs the whole version, such as ==2.28, takes it.
What widen does per ecosystem
Section titled “What widen does per ecosystem”| Ecosystem | widen |
|---|---|
| npm | adds an alternative: ^1.0.0 || 2.0.0; a peer range gets a caret alternative, ^5 || ^7.0.0 |
| Cargo | a convex interval keeping the original minimum, >=1.2.3, <3.0.0, because a Cargo requirement cannot be a union |
| Composer | adds an alternative covering the target: ^1.2 || ^3.0 |
| Poetry | adds an alternative covering the target: ^1.2 || ^3.0 |
| PEP 440 (PEP 621, uv) | a declaration that is a single upper-bound clause is raised, <2 to <=3.1.4; a compound one such as >=1, <2 is reported as a notice instead, and other single specifiers cannot be unions, so they shift as under preserve |
| Terraform | as PEP 440: a single upper-bound clause is raised, anything else shifts as under preserve |
| Maven, NuGet | a single interval takes the target as its inclusive upper bound, [1.0,2.0) to [1.0,3.1]; several intervals are not rewritten |
| Bundler | as preserve: , only means “and”, so a requirement cannot be extended |
| Docker, Go, mise tools and single-version toolchain pins | as preserve: a declaration is one version, so every policy writes the target |
Ranged toolchain constraints (engines.node, Terraform required_version) |
preserve leaves them alone, since widening a supported runtime range needs compatibility evidence the Count does not have |
The default depends on the ecosystem
Section titled “The default depends on the ecosystem”The default is exact for most dependencies, and preserve for Cargo,
pyproject (PEP 621 and Poetry), Bundler and Composer. A built-in rule in the
schema sets it, with a note saying why: these ecosystems resolve one version
per package, and a lockfile records it.
- A pin adds nothing over the lockfile. The lock already says exactly which version is installed.
- A pin can clash with other requirements on the same package. A direct
=0.23.1in Cargo fails to resolve when another crate in the tree needs^0.23.2, where a range lets the resolver pick one version for both.
npm and Bun stay exact, so installs are reproducible without
relying on a lockfile alone; see Exact npm versions.
engines.node and Terraform’s required_version declare the runtimes a
project supports rather than the one it installs, so they default to
preserve too: a release the constraint allows changes nothing, and one past
its ceiling is left alone. A version file such as .nvmrc, .node-version
or .terraform-version pins the installed version and is updated like any
other pin, and a partial version updates to an exact pin: .nvmrc holding
20 is written as an exact version such as 20.19.0.
Under preserve a release the declaration already allows does not edit the
manifest. When the manifest has a committed lockfile, the update moves that
lock to the new version and nothing else, so tokio = "1" locked at 1.39.0
still gets 1.40.0:
| Lockfile | How the lock moves to the chosen version |
|---|---|
Cargo.lock |
cargo update -p tokio@1.39.0 --precise 1.40.0 |
uv.lock |
uv lock --upgrade-package tokio==1.40.0 |
poetry.lock |
Poetry cannot be told a version, so the constraint is pinned for one poetry lock and restored for a second |
Gemfile.lock |
Bundler cannot be told a version either, so the requirement is pinned for one bundle lock --update and restored for a second bundle lock |
composer.lock |
composer update <package> --with <package>:1.40.0 |
The PR, branch and commit read like any other update (update tokio to 1.40.0),
and the release-age wait,
windows, grouping and permitted all apply. The Count reads the new lock back
and refuses to publish if it does not record the target. The version the
update starts from is the locked one, not the range’s floor.
With no committed lockfile there is nothing to change, so a release inside the
range is not an update. npm and Bun lockfiles have no such command: if you set
versions = "preserve" for them, an in-range release is still left out, and
only the scheduled lockfile refresh
moves the lock.
To go back to pins everywhere, add a rule after the built-in one:
rules { new Rule { note = "Pin everything." select { managers { "cargo"; "pyproject"; "bundler"; "composer" } } apply { versions = "exact" } }}The built-in rules come first, so a rule of yours overrides them. Assigning a
new Listing to rules drops them, and with them this default and the
reference data fast track.
Installed npm dependencies follow versions, so by default they are pinned
exactly. Peer dependencies describe what consumers may use, so they are
treated differently: a range widens at a new major (^5 becomes
^5 || ^7.0.0), an exact peer bumps in place, and exact policy never pins a
peer range.
Cargo’s preserve keeps a satisfying floor, and a two-part requirement that
crosses a major starts at the new major’s floor (0.30 becomes 1.0 for
1.1.0). A Terraform provider constraint that already allows the new version is
left as written, even under exact policy.
Docker tags
Section titled “Docker tags”Numeric tags can have more than three parts, and the suffix after the number is
a compatibility label, not a prerelease. 3.12-alpine upgrades to
3.13-alpine, never to 3.13-slim. Floating tags such as latest and opaque
ones get digest updates only.
© 2026 Sweepy
