Versioning

Version identifiers

The syntax of version identifiers in map.apps follows the specification defined in Semantic Versioning 2.0 .

This means that any version consists of the three mandatory components:

  • MAJOR

  • MINOR

  • PATCH

The components are separated by a single period ('.').

Version identifiers

3.1.0

3.1 (invalid, missing PATCH)

Version identifiers can be extended by a pre-release identifier appending a hyphen and a series of dot-separated identifiers.

Version identifiers with pre-release identifier

3.1.0-alpha

3.1.0-alpha.1

Additionally, version identifiers can be extended by a build metadata identifier appending a plus sign and a series of dot-separated identifiers.

Version identifiers with build metadata identifier

3.1.0+20141230.r320964

3.1.0-alpha.1+20141230.r320964

We recommend to use version numbers as specified in Semantic Versioning 2.0 on the semantical level, too. Citing the specification summary, this means:

Increment the:

  1. MAJOR version when you make incompatible API changes,

  2. MINOR version when you add functionality in a backward compatible manner, and

  3. PATCH version when you make backward compatible bug fixes.

The semantic versioning implementation of map.apps has some limitations and special cases.

map.apps supports a 4th version number, the hot-fix version (for example 1.0.0.1). This feature is for backward compatibility only and should not be used.

All version components (major, minor, patch and hot fix) must be between 0 and 999999 only. Leading zeros are not allowed in version numbers. Numbers between dots in pre-release versions are treated as numbers and are also restricted to the range between 0 and 999999.

The following list explains the rules using examples:

  • 999999.999999.999999: Highest allowed version number

  • 01.0.0: Not allowed because of leading zero in major

  • 1.01.0: Not allowed because of leading zero in minor

  • 1.0.01: Not allowed because of leading zero in patch

  • 1.0.0-SNAPSHOT.1: The .1 is interpreted as number

  • 1.0.0-SNAPSHOT-1: The -1 is interpreted as string

  • 1.0.0-SNAPSHOT.01: The .01 is not allowed because of leading zeros

  • 1.0.0-SNAPSHOT-01: The -01 is allowed and interpreted as string

  • 1.0.0-SNAPSHOT.999999: The .999999 is allowed and the highest supported number

  • 1.0.0-SNAPSHOT.0999999: The .0999999 is not allowed because of leading zero

  • 1.0.0-SNAPSHOT.1999999: The .1999999 is not allowed because it is to high

  • 1.0.0-SNAPSHOT-1999999: The -1999999 is allowed and interpreted as string

In map.apps versions before 4.13 the -<number> expressions in pre-release parts were wrongly transformed to .<number> expressions. Versions like 1.0.0-SNAPSHOT-1 where silently changed to 1.0.0-SNAPSHOT.1.

Version ranges

map.apps uses the version range syntax defined by the semver tool of the Node Package Manager (npm).

1.2.3

Specific version 1.2.3. Build metadata is still ignored, so "1.2.3+build2012" satisfies this range.

>1.2.3

Greater than 1.2.3 version.

<1.2.3

Less than 1.2.3. If there is no prerelease tag on the version range, no prerelease version is allowed, even though these are technically "less than".

>=1.2.3

Greater than or equal to 1.2.3. Prerelease versions are NOT equal to their "normal" equivalents, so 1.2.3-beta does not satisfy this range, but 2.3.0-beta will.

<=1.2.3

Less than or equal to 1.2.3. In this case, prerelease versions ARE allowed, so 1.2.3-beta satisfies.

Intersections of ranges

Ranges can be joined by whitespace to express an intersection ("and") of ranges.

>=3.1.0 <4.0.0

Greater than or equal to 3.1.0 and less than 4.0.0, so 3.2.0 is satisfied.

3.1.0 - 4.0.0

Equivalent to >=3.1.0 ⇐4.0.0, using special "hyphen" syntax

If ranges are joined using '||' (double pipe) it is interpreted as "or".

3.1.0 || 3.1.1

Version 3.1.0 or 3.1.1

3.1.0 || >= 3.1.2 <3.2.0

"3.1.0" or "greater or equal to 3.1.2 but less than 3.2.0"

Advanced syntax

~1.2.3

Equivalent to >=1.2.3-0 <1.3.0-0. "Reasonably close to 1.2.3". When using tilde operators, prerelease versions are supported as well, but a prerelease of the next significant digit does NOT satisfy, so 1.3.0-beta does not satisfy ~1.2.3.

^1.2.3

Equivalent to >=1.2.3-0 <2.0.0-0. "Compatible with 1.2.3". When using caret operators, anything from the specified version (including prerelease) is supported up to, but not including, the next major version (or its prereleases). 1.5.1 satisfies ^1.2.3, while 1.2.2 and 2.0.0-beta does not.

^0.1.3

Equivalent to >=0.1.3-0 <0.2.0-0. "Compatible with 0.1.3". 0.x.x versions are special: the first non-zero component indicates potentially breaking changes, meaning the caret operator matches any version with the same first non-zero component starting at the specified version.

^0.0.2

Equivalent to =0.0.2. "Only the version 0.0.2 is considered compatible".

~1.2

Equivalent to >=1.2.0-0 <1.3.0-0 "Any version starting with 1.2".

^1.2

Equivalent to >=1.2.0-0 <2.0.0-0 "Any version compatible with 1.2".

1.2.x

Equivalent to >=1.2.0-0 <1.3.0-0 "Any version starting with 1.2".

~1

Equivalent to >=1.0.0-0 <2.0.0-0 "Any version starting with 1".

^1

Equivalent to >=1.0.0-0 <2.0.0-0 "Any version compatible with 1".

1.x

Equivalent to >=1.0.0-0 <2.0.0-0 "Any version starting with 1"

*

Equivalent to >= 0.0.0. Any range.