Versioning

Once Managers have extracted dependencies, and Datasources have located available versions, then Renovate makes use of "Versioning" schemes to perform sorting and filtering of results. This is necessary because different managers use different types of numbering/versioning, e.g. 1.0.0-beta.1 in npm and 1.0.0b1 in Python.

Configuring Versioning

There are times when you may need to manually configure/override the versioning value for a particular dependency. You generally won't have a need for this in ecosystems with strict versioning enforcement like npm, but you might often need it for ecosystems like Docker where versioning is barely a "convention". e.g.

{
  "packageRules": [
    {
      "datasources": ["docker"],
      "packageNames": ["python"],
      "versioning": "pep440"
    }
  ]
}

The above will override Renovate's default of docker versioning for the python Docker image and instead use pep440 versioning to evaluate versions.

Supported Versioning

Supported values for versioning are: cargo, composer, docker, git, gradle, hashicorp, hex, ivy, loose, maven, node, npm, nuget, pep440, poetry, regex, ruby, semver, swift.

Cargo Versioning

Identifier: cargo

References:

Ranges/Constraints:

✅ Ranges are supported.

Valid rangeStrategy values are: bump, extend, 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:

Ranges/Constraints:

✅ Ranges are supported.

Valid rangeStrategy values are: bump, extend, pin, replace

Description:

Composer uses Semver-like versioning, however 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


Docker Versioning

Identifier: docker

References:

Ranges/Constraints:

❌ No range support.

Description:

Docker doesn't really have versioning, instead it supports "tags" and these are usually used by Docker image authors as a form of versioning.

This Docker versioning implementation in Renovate is designed to handle the most common conventions used in tagging images. In particular, it treats the text after the first hyphen as a type of platform/compatibility indicator.

For example, many images include images with the "-alpine" suffix, e.g. the official node Docker image includes tags like 12.15.0-alpine which is not compatible with 12.15.0 or 12.15.0-stretch. This means users only want/expect upgrades to 12.16.0-alpine and not 12.16.0 or 12.16.0-stretch.

Similarly, a user with 12.14 expects to be upgraded to 12.15 and not 12.15.0.

What type of versioning is used?

It's pretty "wild west" for tagging and not always compliant with semver. Docker versioning in Renovate should do a best effort to accept and sort semver-like versions.

Are ranges supported?

No. Although a tag like 12.15 might seem like it means 12.15.x, it is a tag of its own and may or may not point to an of the available 12.15.x tags, including 12.15.0.


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.


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, extend, 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.


Hex Versioning

Identifier: hex

References:

Ranges/Constraints:

✅ Ranges are supported.

Valid rangeStrategy values are: bump, extend, 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, extend, pin, replace


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 it just does its best to sort versions.


Maven Versioning

Identifier: maven

References:

Ranges/Constraints:

✅ Ranges are supported.

Valid rangeStrategy values are: bump, extend, 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.


Node.js Versioning

Identifier: node

Ranges/Constraints:

❌ No range support.

Description:

Renovate's Node.js versioning is a wrapper around npm's versioning, except that it makes sure to strip "v" prefixes from exact versions when replacing.

It is planned to extend it one day to support "stability" awareness, because Node.js's version stability does not follow the SemVer approach.


npm Versioning

Identifier: npm

References:

Ranges/Constraints:

✅ Ranges are supported.

Valid rangeStrategy values are: bump, extend, 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, extend, 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.


Poetry Versioning

Identifier: poetry

References:

Ranges/Constraints:

✅ Ranges are supported.

Valid rangeStrategy values are: bump, extend, pin, replace

Description:

Poetry versioning is a little like a mix of PEP440 and SemVer.

Currently Renovate's implementation is based off npm versioning, but it is being migrated to be based off PEP440 to be more compatible with Poetry's behaviour.


Regular Expression Versioning

Identifier: regex

Ranges/Constraints:

❌ No range support.

Description:

Regular Expression Versioning is designed to be like a flexible fallback versioning approach is 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, and patch: at least one of these must be provided. When determining whether a package has updated, 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 were 0 -- in this way, you can describe versioning schemes with up to three incrementing values.
  • prerelease: this value, if captured, will mark a given release as a prerelease (eg. 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 to 1.2.3-linux (and linux is captured as the compatbility value), Renovate will not update you to 1.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": [
    {
      "packageNames": ["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": [
    {
      "datasources": ["docker"],
      "packageNames": ["python"],
      "versioning": "regex:^(?<major>\\d+)\\.(?<minor>\\d+)\\.(?<patch>\\d+)(?<prerelease>[^.-]+)?(-(?<compatibility>.*))?$"
    }
  ]
}

Ruby Versioning

Identifier: ruby

References:

Ranges/Constraints:

✅ Ranges are supported.

Valid rangeStrategy values are: bump, extend, 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, as per the specification.


Swift Versioning

Identifier: swift

References:

Ranges/Constraints:

✅ Ranges are supported.

Valid rangeStrategy values are: bump, extend, 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.