Versioning¶
Once Managers have extracted dependencies, and Datasources have located available versions, then Renovate will use a "Versioning" scheme to perform sorting and filtering of results.
The "versioning" is different for each package manager, because different package managers use different versioning schemes.
For example, npm
uses1.0.0-beta.1
and pip
uses 1.0.0b1
.
Why you might need to manually configure versioning¶
Renovate interprets versions correctly out-of-the-box most of the time. It's impossible to automatically detect all versioning schemes, so sometimes you need to tell the bot what versioning scheme it should use.
You can manually configure/override the versioning
value for a particular dependency.
You generally won't need to override the defaults for ecosystems which enforce a strict version scheme like npm
.
Configuring or overriding the default versioning
can be particularly helpful for ecosystems like Docker/Kubernetes/Helm, where versioning is barely a "convention".
General concepts behind overriding versioning¶
- Although you can reconfigure versioning per-manager or per-datasource, it's unlikely that such a broad change would ever be needed
- More commonly you would need to configure
versioning
for individual packages or potentially package patterns - The best way to do this is with
packageRules
, with a combination ofmatchManagers
,matchDatasources
,matchPackageNames
andmatchPackagePatterns
. Avoid configuringversioning
in a rule that also usesmatchUpdateTypes
, as the update types aren't known at the time theversioning
is applied.
Examples of versioning overrides¶
Overriding Docker versioning to use a versioning specific for a package¶
The configuration below overrides Renovate's default docker
versioning for the python
Docker image and instead uses the pep440
versioning scheme to evaluate versions.
{
"packageRules": [
{
"matchDatasources": ["docker"],
"matchPackageNames": ["python"],
"versioning": "pep440"
}
]
}
Using a custom regex versioning scheme¶
{
"packageRules": [
{
"matchPackageNames": ["foo/bar"],
"versioning": "regex:^(?<compatibility>.*)-v?(?<major>\\d+)\\.(?<minor>\\d+)\\.(?<patch>\\d+)?$"
}
]
}
Supported Versioning¶
Supported values for versioning
are: aws-machine-image
, azure-rest-api
, bazel-module
, cargo
, composer
, conan
, deb
, debian
, docker
, git
, go-mod-directive
, gradle
, hashicorp
, helm
, hermit
, hex
, ivy
, kubernetes-api
, loose
, maven
, nixpkgs
, node
, npm
, nuget
, pep440
, perl
, poetry
, python
, redhat
, regex
, rez
, ruby
, semver
, semver-coerced
, swift
, ubuntu
.
aws-machine-image Versioning¶
Identifier: aws-machine-image
Ranges/Constraints:
❌ No range support.
Description:
Renovate's AWS Machine Image versioning is a kind of hack to support Amazon Machine Images (AMI) updates.
At the moment every AMI that matches the regex ^ami-[a-z0-9]{17}$
is considered a valid "release".
azure-rest-api Versioning¶
Identifier: azure-rest-api
References:
Ranges/Constraints:
❌ No range support.
Description:
The Azure REST APIs use a YYYY-MM-DD
version with an optional -preview
suffix: https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md#api-versioning
Internally at Microsoft they are using other additional suffixes: https://github.com/Azure/bicep/blob/a1d217e3bb3d049fc5c6c21b466c3a29585a6c69/src/Bicep.Core/Analyzers/Linter/ApiVersions/ApiVersionHelper.cs#L15
Bazel Module Versioning¶
Identifier: bazel-module
References:
Ranges/Constraints:
❌ No range support.
Cargo Versioning¶
Identifier: cargo
References:
Ranges/Constraints:
✅ Ranges are supported.
Valid rangeStrategy
values are: bump
, pin
, replace
Description:
Cargo versioning uses Semantic Versioning 2.0.
Cargo supports ranges in a similar manner to npm, but not identical. The important differences are:
Use of commas
Multiple version requirements can also be separated with a comma, e.g. >= 1.2, < 1.5
. We interpret this to mean AND.
No exact versions unless using equals =
In Cargo, 1.2.3
doesn't mean "exactly 1.2.3", it actually means >=1.2.3 <2.0.0
. So this is like the equivalent of ^1.2.3
in npm.
Composer Versioning¶
Identifier: composer
References:
- https://getcomposer.org/doc/articles/versions.md
- https://packagist.org/packages/composer/semver
- https://madewithlove.be/tilde-and-caret-constraints/
- https://semver.mwl.be
Ranges/Constraints:
✅ Ranges are supported.
Valid rangeStrategy
values are: bump
, widen
, pin
, replace
, update-lockfile
Description:
Composer uses Semver-like versioning, but some package authors may use versions that are not completely valid, e.g. 1.2
instead of 1.2.0
.
Composer supports ranges in a similar manner to npm, but not identical. The main difference is with tilde ranges.
Tilde ranges with "short" versions are different to npm. e.g.
~4
is equivalent to ^4
in npm
~4.1
is equivalent to ^4.1
in npm
~0.4
is equivalent to >=0.4 <1
in npm
Composer supports patches in the version numbers, which are considered stable. E.g., 1.2.3-p1
is recognized by npm as unstable, Renovate
implements additional logic to support correct sorting and stability checks on composer patch versions syntax.
conan Versioning¶
Identifier: conan
References:
- https://semver.org/
- https://github.com/podhmo/python-node-semver
- https://github.com/podhmo/python-node-semver/tree/master/examples
- https://docs.conan.io/en/latest/versioning/version_ranges.html#version-ranges
Ranges/Constraints:
✅ Ranges are supported.
Valid rangeStrategy
values are: auto
, bump
, widen
, replace
Description:
Conan versioning supports Semantic Versioning 2.0 but some packages don't follow this specification.
Conan implements python-node-semver.
Read the Conan docs about version ranges for more information.
syntax | description |
---|---|
5.45 |
Equivalent to 5.45 |
16.00 |
Equivalent to 16.00 |
2.8.3 |
Equivalent to 2.8.3 |
[>1.1 <2.1] |
Keep version within range |
[2.8] |
Equivalent to =2.8 |
[~=3.0] |
Compatible, according to SemVer |
[>1.1 \|\| 0.8] |
Conditions can be OR'ed |
[1.2.7 \|\| >=1.2.9 <2.0.0] |
This range would match the versions 1.2.7 , 1.2.9 , and 1.4.6 , but not the versions 1.2.8 or 2.0.0 |
[>1.1 <2.1, include_prerelease=True] |
Would e.g. accept 2.0.0-pre.1 as match |
[~1.2.3, loose=False] |
Would only accept correct Semantic Versioning strings. E.g. version 1.2.3.4 would not be accepted |
[~1.2.3, loose=False, include_prerelease=True] |
Both options can be used for the same version range |
Deb version Versioning¶
Identifier: deb
References:
- https://www.debian.org/doc/debian-policy/ch-controlfields.html#version
- https://manpages.debian.org/unstable/dpkg-dev/deb-version.7.en.html
Ranges/Constraints:
❌ No range support.
Description:
Deb versioning compares versions like package managers on Debian-based Linux distributions compare packages (dpkg
, apt
).
Deb versioning supports complicated version numbers, including alphabetical characters almost everywhere.
Similar to our "loose" versioning, deb versioning is a "best effort" attempt to convert deb versions to SemVer fields like major
, minor
, patch
.
Debian Versioning¶
Identifier: debian
References:
Ranges/Constraints:
✅ Ranges are supported.
Valid rangeStrategy
values are: pin
Description:
Debian versioning is used for Debian container images that are referenced by their major release version or a codename.
Versions to which this scheme applies are e.g. 11
and bullseye
.
Container image tags such as 11-slim
, 11.4
or 11.4-slim
, bullseye-20220822
or bullseye-backports
are not compliant with the current implementation.
Docker Versioning¶
Identifier: docker
References:
Ranges/Constraints:
❌ No range support.
Description:
Docker images don't really have versions, instead they have "tags". Tags are often used by Docker image authors as a form of versioning.
Renovate tries to follow the most common conventions that are used to tag Docker images. In particular, Renovate treats the text after the first hyphen as a type of platform/compatibility indicator.
For example, many images have releases with the -alpine
suffix.
The official node
Docker image has tags like 12.15.0-alpine
which is not compatible with 12.15.0
or 12.15.0-stretch
.
Users on -alpine
don't want updates to 12.16.0
or 12.16.0-stretch
.
Those users only want upgrades to 12.16.0-alpine
and not 12.16.0
or 12.16.0-stretch
.
Similarly, a user on 12.14
expects to be upgraded to 12.15
and not 12.15.0
.
What type of versioning is used?
Docker image authors can use whatever tag they want, it's a "wild west". Docker tags don't always follow SemVer. This means that Renovate tries to accept and sort SemVer-like versions, but this won't always work.
You may need to help Renovate and create your own rules for some Docker images. For example:
{
"packageRules": [
{
"matchDatasources": ["docker"],
"matchPackageNames": ["badly-versioned-docker-image"],
"versioning": "loose"
}
]
}
Are ranges supported?
No.
You may think a tag like 12.15
also means 12.15.x
, but it's a tag of its own.
The 12.15
tag may or may not point to any of the available 12.15.x
tags, including 12.15.0
.
Are commit hashes supported?
No, Renovate ignores Docker image tags that look like a Git commit hash.
git Versioning¶
Identifier: git
References:
Ranges/Constraints:
❌ No range support.
Description:
Renovate's Git versioning is a kind of hack to support Git submodule updating.
Go Modules Directive Versioning¶
Identifier: go-mod-directive
References:
Ranges/Constraints:
✅ Ranges are supported.
Valid rangeStrategy
values are: bump
, replace
Description:
This versioning is used exclusively for the go
directive in go.mod
files.
It ensures that a value like 1.16
is treated like ^1.16
and not ~1.16
.
By default this will mean that the go
directive in go.mod
files won't get upgraded to any new Go version, such as 1.19
.
If you wish to upgrade this value every time there's a new minor Go release, configure rangeStrategy
to be "bump"
like so:
{
"packageRules": [
{
"matchDatasources": ["golang-version"],
"rangeStrategy": "bump"
}
]
}
Gradle Versioning¶
Identifier: gradle
References:
Ranges/Constraints:
✅ Ranges are supported.
Valid rangeStrategy
values are: pin
Hashicorp Versioning¶
Identifier: hashicorp
References:
Ranges/Constraints:
✅ Ranges are supported.
Valid rangeStrategy
values are: bump
, widen
, pin
, replace
Description:
Hashicorp versioning syntax is used for Terraform.
It is based off Semantic Versioning 2.0 but with a subset of npm's range syntax.
helm Versioning¶
Identifier: helm
References:
- https://semver.org/
- https://helm.sh/docs/chart_best_practices/dependencies/#versions
- https://github.com/Masterminds/semver#basic-comparisons
Ranges/Constraints:
✅ Ranges are supported.
Valid rangeStrategy
values are: bump
, widen
, pin
, replace
, widen
Hermit Versioning¶
Identifier: hermit
References:
Ranges/Constraints:
❌ No range support.
Description:
Hermit versioning is a mix of version
and channel
.
Version
Hermit's package version comes from the package's original Git tag.
The version is an extension to SemVer, with an extra build number to accommodate package versions from OpenJDK, which has a value 15.0.1_9
.
Channel
Channel could be Hermit-generated or user-defined. Channel is considered unstable version and normally won't upgrade. If you would like to get out of Channel, you could replace the Channel with a given version number and let Renovate manage it.
Hex Versioning¶
Identifier: hex
References:
Ranges/Constraints:
✅ Ranges are supported.
Valid rangeStrategy
values are: bump
, widen
, pin
, replace
Description:
Hex versioning syntax is used for Elixir and Erlang hex dependencies. It is based on Semantic Versioning 2.0 and supports a subset of npm's range syntax.
Ivy Versioning¶
Identifier: ivy
References:
Ranges/Constraints:
✅ Ranges are supported.
Valid rangeStrategy
values are: bump
, widen
, pin
, replace
Kubernetes API Versioning¶
Identifier: kubernetes-api
References:
Ranges/Constraints:
❌ No range support.
Loose Versioning¶
Identifier: loose
Ranges/Constraints:
❌ No range support.
Description:
Renovate's "loose" versioning was created for cases where no strict versioning is in place. It works like SemVer if SemVer-compliant versions are supplied, but otherwise is "best effort". Essentially "loose" versioning does its best to sort versions and ignores "unsortable" versions.
Maven Versioning¶
Identifier: maven
References:
- https://maven.apache.org/pom.html#Dependency_Version_Requirement_Specification
- https://octopus.com/blog/maven-versioning-explained
- https://maven.apache.org/enforcer/enforcer-rules/versionRanges.html
Ranges/Constraints:
✅ Ranges are supported.
Valid rangeStrategy
values are: bump
, widen
, pin
, replace
Description:
Maven versioning is similar to SemVer but also very different in places. It's specified by Maven itself.
Ranges are supported using Maven's special syntax.
For development purposes, download maven-artifact JAR and run:
$ java -jar maven-artifact-*.jar 3.2.4-alpha-1 3.2.4-SNAPSHOT 3.2.4.0
Display parameters as parsed by Maven (in canonical form) and comparison result:
1. 3.2.4-alpha-1 == 3.2.4.alpha.1
3.2.4-alpha-1 < 3.2.4-SNAPSHOT
2. 3.2.4-SNAPSHOT == 3.2.4.snapshot
3.2.4-SNAPSHOT < 3.2.4.0
3. 3.2.4.0 == 3.2.4
Nixpkgs Versioning¶
Identifier: nixpkgs
References:
Ranges/Constraints:
❌ No range support.
Description:
Nixpkgs versioning is designed to be used with the nix manager.
NixOS releases follow the YY.MM
pattern.
There are also some prefixes and suffixes allowed.
Using 22.05
as an example the allowed combination of prefixes and suffixes are:
release-22.05
nixos-22.05
nixos-22.05-small
nixos-22.05-aarch64
nixpkgs-22.05-darwin
Additionally, there are some floating versions:
nixos-unstable
nixos-unstable-small
nixpkgs-unstable
Node.js Versioning¶
Identifier: node
Ranges/Constraints:
❌ No range support.
Description:
Renovate's Node.js versioning is a wrapper around npm versioning.
But Renovate removes any v
prefixes from semantic versions when replacing.
Its primary purpose is to add Node.js LTS awareness, e.g.:
- Odd releases are unstable
- Even releases do not reach stability (LTS) immediately
You can not use node
versioning to replace docker
versioning if you are using node tags with suffixes like -alpine
.
This is because npm versioning treats these suffixes as implying pre-releases/instability.
npm Versioning¶
Identifier: npm
References:
- https://semver.org/
- https://www.npmjs.com/package/semver
- https://docs.npmjs.com/about-semantic-versioning
- https://semver.npmjs.com/
Ranges/Constraints:
✅ Ranges are supported.
Valid rangeStrategy
values are: bump
, widen
, pin
, replace
Description:
npm versioning is the most well known/widely-used implementation of Semantic Versioning 2.0.
It's important to understand that "npm" versioning scheme is not the same as "semver" versioning. SemVer's spec does not define ranges at all - so all range/constraint syntax in npm is npm-specific and not part of the spec.
NuGet Versioning¶
Identifier: nuget
References:
Ranges/Constraints:
❌ No range support.
Description:
NuGet versioning matches as closely as possible to the version comparison that NuGet itself uses.
NuGet supports SemVer 2.0.0, but permits versions with differing numbers of version parts.
Ranges are not yet supported by this versioning, but they are defined in NuGet and could be supported in the future.
PEP440 Versioning¶
Identifier: pep440
References:
Ranges/Constraints:
✅ Ranges are supported.
Valid rangeStrategy
values are: bump
, widen
, pin
, replace
Description:
PEP 440 is defined as part of the Python project, and its versioning is independent of others such as SemVer.
Ranges are supported using the syntax defined as part of the PEP440 spec.
Perl Versioning¶
Identifier: perl
References:
Ranges/Constraints:
❌ No range support.
Description:
Perl versioning is based on Perl's version
module.
This could be used in combination with the regex
manager and the cpan
datasource.
Poetry Versioning¶
Identifier: poetry
References:
Ranges/Constraints:
✅ Ranges are supported.
Valid rangeStrategy
values are: bump
, widen
, pin
, replace
Description:
Poetry versioning is a little like a mix of PEP440 and SemVer.
Currently Renovate's implementation is based off npm versioning.
This works by parsing versions using the same patterns and similar normalization rules as Poetry, passing them to the npm versioning implementation, and then reversing the normalizations.
This allows Renovate to meaningfully compare the SemVer-style versions allowed in pyproject.toml
to the PEP440 representations used on PyPI.
These are equivalent for major.minor.patch releases, but different for pre-, post-, and dev releases.
Python Versioning¶
Identifier: python
Ranges/Constraints:
❌ No range support.
Description:
Python versioning is a little like a mix of PEP440 and Poetry SemVer.
Red Hat Versioning¶
Identifier: redhat
Ranges/Constraints:
❌ No range support.
Description:
Red Hat versioning is used with container images that are maintained by Red Hat.
Red Hat version definitions follow this pattern:
- the version of the main component, where major is required, but minor and patch are optional
- optionally a hyphen followed by release information
- the version of Red Hat's release as an integer, optionally followed by a timestamp like:
1645808164
Examples of valid Red Hat versions:
1
8.5
7.9-628
9.0.0-19.1655192132
Ranges are not supported by this versioning.
Regular Expression Versioning¶
Identifier: regex
Ranges/Constraints:
❌ No range support.
Description:
Regular Expression Versioning is designed to be a flexible fallback versioning approach if Renovate's other versioning schemes don't do the job.
The regex
scheme makes use of Regular Express capture groups.
The valid capture groups for regex
versioning are:
major
,minor
, andpatch
: at least one of these must be provided. When determining whether a package has updates, these values will be compared in the standard semantic versioning fashion. If any of these fields are omitted, they will be treated as if they were0
-- in this way, you can describe versioning schemes with up to three incrementing values.build
: this capture group can be used after you've already used themajor
,minor
andpatch
capture groups and need a fourth version part.build
updates are handled likepatch
updates.revision
: this capture group can be used after you've already used thebuild
capture groups and need a fifth version part.revision
updates are handled likepatch
updates.prerelease
: this value, if captured, will mark a given release as a prerelease (e.g. unstable). If this value is captured and you have configured"ignoreUnstable": true
, the given release will be skipped.compatibility
: this value defines the "build compatibility" of a given dependency. A proposed Renovate update will never change the specified compatibility value. For example, if you are pinning to1.2.3-linux
(andlinux
is captured as the compatibility value), Renovate will not update you to1.2.4-osx
.
The compatibility concept was originally introduced for Docker versioning but sometimes package authors may use/misuse suffixes to mean compatibility in other versioning schemes.
Here is an example of using regex
versioning to correct behavior of the guava
Maven package, which misuses suffixes as compatibility indicators:
{
"packageRules": [
{
"matchPackageNames": ["com.google.guava:guava"],
"versioning": "regex:^(?<major>\\d+)(\\.(?<minor>\\d+))?(\\.(?<patch>\\d+))?(-(?<compatibility>.*))?$"
}
]
}
Here is another example, this time for handling python
Docker images, which use both pre-release indicators as well as version suffixes for compatibility:
{
"packageRules": [
{
"matchDatasources": ["docker"],
"matchPackageNames": ["python"],
"versioning": "regex:^(?<major>\\d+)\\.(?<minor>\\d+)\\.(?<patch>\\d+)(?<prerelease>[^.-]+)?(-(?<compatibility>.*))?$"
}
]
}
Here is another example, this time for handling Bitnami Docker images, which use build
and revision
indicators as well as version suffixes for compatibility:
{
"packageRules": [
{
"matchDatasources": ["docker"],
"matchPackagePrefixes": ["bitnami/"],
"versioning": "regex:^(?<major>\\d+)\\.(?<minor>\\d+)\\.(?<patch>\\d+)(?:-(?<compatibility>.+)(?<build>\\d+)-r(?<revision>\\d+))?$"
}
]
}
rez Versioning¶
Identifier: rez
References:
Ranges/Constraints:
✅ Ranges are supported.
Valid rangeStrategy
values are: bump
, widen
, pin
, replace
Description:
rez versioning was developed to support the rez Package Manager. It's based on Semantic Versioning but includes its own concept of ranges.
Use of dots
A range is expressed with dots 1.2..2
means >=1.2.x <2.0.0
.
No exact versions unless using two equals ==
In rez, 1.2.3
doesn't mean "exactly 1.2.3", it actually means >= 1.2.3 <1.2.4
.
If you want to use an exact version use two equal characters, like this: ==1.2.3
.
Use of pipes
rez uses pipes as an OR operator, 2.7..3|4
means >=2.7 <3 OR 4.x.x
.
This has not been implemented yet. The current iteration of rez versioning does not support pipes yet.
Ruby Versioning¶
Identifier: ruby
References:
- https://guides.rubygems.org/patterns/
- https://bundler.io/v1.5/gemfile.html
- https://www.devalot.com/articles/2012/04/gem-versions.html
Ranges/Constraints:
✅ Ranges are supported.
Valid rangeStrategy
values are: bump
, widen
, pin
, replace
Description:
The RubyGems team urges gem developers to follow the Semantic Versioning standard for their gem’s versions, but it is not enforced.
Range syntax is similar to npm's but not identical. The main difference is the use of "pessimistic" greater than or equals: ~>
Semantic Versioning¶
Identifier: semver
References:
Ranges/Constraints:
❌ No range support.
Description:
Renovate's Semantic Versioning is a strict/independent implementation of Semantic Versioning 2.0. It has been developed to be used in situations where exact-only SemVer support is needed and not npm's extended semver implementation including ranges.
Ranges are not supported, in line with the specification.
Coerced Semantic Versioning Versioning¶
Identifier: semver-coerced
References:
Ranges/Constraints:
❌ No range support.
Description:
Renovate's Coerced Semantic Versioning is a forgiving variant of Semantic Versioning 2.0 with coercion enabled for versions.
This versioning provides a very forgiving translation of inputs in non-strict-SemVer format into strict SemVer. For example, "v1" is coerced into "1.0.0", "2.1" => "2.1.0", "~3.1" => "3.1.0", "1.1-foo" => "1.1.0". Look at the Coercion section of this page for more info on input coercion.
Since this versioning is very forgiving, it doesn't actually provide the coercion for version ranges. The range functions only accept strict SemVer as input and equivalent to those provided by the Renovate's semver versioning.
Swift Versioning¶
Identifier: swift
References:
Ranges/Constraints:
✅ Ranges are supported.
Valid rangeStrategy
values are: bump
, widen
, pin
, replace
Description:
Swift versioning was developed to support the Swift Package Manager. It's based on Semantic versioning but includes its own concept of ranges.
Ubuntu Versioning¶
Identifier: ubuntu
References:
- https://changelogs.ubuntu.com/meta-release
- https://debian.pages.debian.net/distro-info-data/ubuntu.csv
Ranges/Constraints:
❌ No range support.
Description:
Ubuntu versioning is used for Ubuntu container images that are referenced by their release version or a codename.
Versions to which this scheme applies are e.g. 22.04
and jammy
.
Container image tags such as jammy-20220815
or focal-20220826
are not compliant with the current implementation.