Package Versioning
Specific packages are referred with an identifier and an exact version number. The version number should reflect the same version as the (software) component it installs.
When creating a package, you assign a specific version number with an optional pre-release label suffix.
Versions
A version number can be on the form:
Major.Minor.Patch[.Revision][-suffix][+metadata]
Where the components are described as following:
- Major: New functionality with breaking changes.
- Minor: Backwards compatible new functionality.
- Patch: Bugfix or minor changes.
- Revision: Other changes.
- -suffix: (Optional) Pre-release label.
- +metadata: (Optional) Build metadata.
For example:
1.0
2.0.4
1.1-alpha
4.2-beta.1
3.0.0-rc.1+build.241
It's recommended that a package version should reflect the actual software component's version. In the wild, software components follow various versioning guidelines.
Update Service follows the Semantic Versioning V2.0.0 scheme, which is supported and recommended when picking a versioning scheme for your software.
Version Ranges
A version range is a set of comparators and comparators are split into operator and version. Available operators are:
- < Less than.
- <= Less than or equal to.
- > Greater than.
- >= Greater than or equal to.
- = Equal to.
For example, version range >=1.3 would match 1.3, 1.6 and 2.0 but not 0.0.1, 0.9 or 1.2.
Version range can include multiple comparators, joined by whitespace, which is satisfied by the intersection of all of the comparators it includes.
For example, version range >=1.2.8 <2.0 would match 1.2.9, 1.8.1 and 1.9, but not 1.0, 2.0 or 2.1.
Version range can also consist of the union of two sets of ranges, separated by ||.
For example, version range 1.9 || >=2.0 <3.0, would match 1.9, 2.0 and 2.5 but not 1.0, 1.10 or 3.0.
Version Query
Version query selects one version from a version range according to applied query symbols. The query symbols are:
- ^: Select the latest version.
- _: Select the lowest version.
- !: Always update.
- -: Only update if necessary.
- *: Include pre-releases
The version query is on the form
[(^|_)(!|-)*] [version range]
As an example, let's say we have the following versions:
1.0.0
1.2.1
1.7.0
2.0.0
2.4.0
2.5.0-beta
Here are some examples of what versions would be selected depending on the version query:
| Version Query | Selected Version |
|---|---|
| ^ | 2.4.0 |
| ^ >=1.0.0 <2.0.0 | 1.7.0 |
| _ | 1.0.0 |
| _ >=1.2.0 <2.4.0 | 1.2.0 |
| *^ | 2.5.0-beta |
| Version Query | Resolves to | Selected Version |
|---|---|---|
| empty | !^ | 2.4.0 |
| 1.2 | >=1.2 <=1.3 | 1.2.1 |
| 1.2.1 | >=1.2.1 <=1.2.2 | 1.2.1 |
Now if we have already have version 2.0.0 installed:
| Version Query | Selected Version |
|---|---|
| !^ | 2.4.0 |
| -^ | 2.0.0 |
Priority
Two or more version ranges can be prioritized with the >> operator. Where a version range on the left side of >> would be prioritized over the right side.
As an example, we have the following versions:
1.0.0
1.2.1
1.7.0
2.0.0
2.4.0
2.5.0-beta
The version query ^ >=1.0.0 <2.0.0 >> >=2.0.0 <3.0.0 would select 1.7.0 while the same query but with union operator (||) ^ >=1.0.0 <2.0.0 || >=2.0.0 <3.0.0 would select 2.4.0.
The version query ^ >=4.0.0 <5.0.0 >> >=2.0.0 <3.0.0 would select 2.4.0 as the prioritized range does not satisfy any of the versions.
Pre-release filters
A pre-release filter can be applied to a version range on the form *-PRE-RELEASE-LABEL, where only pre-releases would satisfy the specified label PRE-RELEASE.
As an example, we have the following versions:
1.0.0-rc.1
1.0.0-rc.2
1.0.0
2.0.0-rc.1
2.0.0
The version range *-rc would select 1.0.0-rc.1, 1.0.0-rc.2 and 2.0.0-rc.1.