A specific package (and hence a job in that package) is always referred to by the package identifier and a version number. Runly packages should follow Semantic Versioning v2.

Versioning Basics

A specific version number is in the form MAJOR.MINOR.PATCH[-SUFFIX], where the components have the following meanings:

  • MAJOR: Breaking changes
  • MINOR: New features, but backwards compatible
  • PATCH: Backwards compatible bug fixes only
  • -SUFFIX (optional): a hyphen followed by a string denoting a prerelease version (following the Semantic Versioning convention).

Examples:

1.0.1
6.11.1231
4.3.1-rc
2.2.44-beta1
3.0.0-alpha.2

Version Ranges

When queueing a job to run on an environment, you have the opportunity to specify an exact version, a version range, or no version at all. If you don’t specify a version, the environment settings for that package will be used to choose a job version.

Examples:

  • *: Match the latest non prerelease version. This is the environment default if no version is specified.
  • 1.4.0: Match exactly version 1.4.0, and no other.
  • ~1.4.0: Match the latest (non prerelease) version from 1.4.0 until last version in 1.4.x line.
  • ~1.4: Equivalent to above.
  • 1.4.x: Equivalent to above.
  • ^1.4.0: Match the latest (non prerelease) version from 1.4.0 until 2.0.0 (not including 2.0.0).
  • >1.4.0: Match the latest (non prerelease) version greater than 1.4.0.
  • >=1.4.0: Match the latest (non prerelease) version greater than or equal to 1.4.0.
  • <=1.4.0: Match the latest (non prerelease) version less than or equal to 1.4.0.

These basic comparators can be joined together by ||. This allows for interesting combinations:

  • 1.4.0 || >= 2.4.0: Matches the version 1.4.0, but also every version equal or greater than 2.4.0. Doesn’t match 1.3.5 or 2.3.9.
  • 1.4.0 || >=1.5.6 <2.4.0: Matches version 1.4.0, 1.5.7, but not 2.4.0.

The job will fail to queue in any of these cases if a version cannot be resolved.

Prerelease Versions

If a version has a prerelease tag (for example, 1.2.3-alpha.3) then it will only be allowed to satisfy comparator sets if at least one comparator with the same MAJOR.MINOR.PATCH tuple also has a prerelease tag.

For example, the range >1.2.3-alpha.3 would be allowed to match the version 1.2.3-alpha.7, but it would not be satisfied by 3.4.5-alpha.9, even though 3.4.5-alpha.9 is technically “greater than” 1.2.3-alpha.3 according to the SemVer sort rules. The version range only accepts prerelease tags on the 1.2.3 version. The version 3.4.5 would satisfy the range, because it does not have a prerelease flag, and 3.4.5 is greater than 1.2.3-alpha.7.