Semver-Vergleicher

What is Semantic Versioning?

Semantic Versioning (SemVer) is a versioning scheme defined by the semver.org specification v2.0.0 that encodes compatibility information directly into version numbers. A SemVer string follows the format MAJOR.MINOR.PATCH where each segment carries precise meaning: incrementing MAJOR signals breaking API changes, MINOR indicates new backward-compatible functionality, and PATCH denotes backward-compatible bug fixes. This convention eliminates ambiguity in dependency management — consumers can programmatically determine whether upgrading a package is safe without reading changelogs. The specification also defines rules for pre-release identifiers (e.g., 1.0.0-alpha.1) and build metadata (e.g., 1.0.0+20231015), enabling teams to publish unstable releases alongside stable ones in a predictable manner.

Semantic Versioning Rules

The SemVer 2.0.0 specification establishes strict rules for version number progression. Once a package reaches 1.0.0, its public API is considered stable and any subsequent change must follow these rules:

• MAJOR (X.y.z): Increment when you make incompatible API changes. Consumers must update their code to accommodate the break. Resets MINOR and PATCH to zero.
• MINOR (x.Y.z): Increment when you add functionality in a backward-compatible manner. Existing consumers continue working unchanged. Resets PATCH to zero.
• PATCH (x.y.Z): Increment when you make backward-compatible bug fixes. No new features, no breaking changes — only corrections to existing behavior.

Versions with a MAJOR of 0 (e.g., 0.3.1) are considered initial development and may introduce breaking changes at any increment. The transition from 0.x.y to 1.0.0 signals that the public API is ready for production consumers and stability guarantees begin.

Version precedence is determined by comparing each dot-separated identifier from left to right. Numeric identifiers are compared as integers: 1.9.0 < 1.10.0 (not lexicographically). A version with more pre-release identifiers has lower precedence than the associated normal version: 1.0.0-alpha < 1.0.0.

Version Range Expressions

Package managers use range expressions to declare which versions of a dependency are acceptable. The most common operators are:

• Caret (^): Allows changes that do not modify the left-most non-zero digit. ^1.2.3 matches >=1.2.3 <2.0.0. For ^0.2.3, it matches >=0.2.3 <0.3.0. This is the default range in npm.
• Tilde (~): Allows patch-level changes. ~1.2.3 matches >=1.2.3 <1.3.0. More conservative than caret — only bug fixes are accepted.
• Comparison operators: >=1.0.0, <2.0.0, >=1.2.0 <1.5.0 define explicit bounds.
• OR operator (||): Combines ranges. >=1.0.0 <1.5.0 || >=2.0.0 accepts either range.
• Hyphen ranges: 1.2.0 - 1.5.0 is equivalent to >=1.2.0 <=1.5.0.
• Wildcard (x or *): 1.2.x matches any patch within 1.2, equivalent to >=1.2.0 <1.3.0.

Understanding these operators is critical for avoiding dependency conflicts. The caret operator is popular because it maximizes compatibility updates while preventing breaking changes from propagating through dependency trees.

Pre-release and Build Metadata

Pre-release versions are denoted by appending a hyphen and a series of dot-separated identifiers after the patch version: 1.0.0-alpha, 1.0.0-beta.2, 2.1.0-rc.1. These identifiers indicate that the version is unstable and may not satisfy normal compatibility requirements.

Precedence for pre-release versions follows specific rules defined in the SemVer spec:

• Numeric identifiers are compared as integers: 1.0.0-alpha.1 < 1.0.0-alpha.2
• Alphanumeric identifiers are compared lexicographically: 1.0.0-alpha < 1.0.0-beta
• Numeric identifiers always have lower precedence than alphanumeric: 1.0.0-1 < 1.0.0-alpha
• A larger set of identifiers has higher precedence when all preceding are equal: 1.0.0-alpha < 1.0.0-alpha.1
• Any pre-release is lower than the release: 1.0.0-rc.9 < 1.0.0

Build metadata is appended with a plus sign: 1.0.0+20231015, 1.0.0-beta+exp.sha.5114f85. Build metadata MUST be ignored when determining version precedence — two versions that differ only in build metadata are considered equal for comparison purposes. Build metadata is useful for tracking build provenance without affecting resolution.

SemVer in Package Managers

Different ecosystems implement SemVer ranges with slight variations in syntax:

• npm / Yarn (Node.js): Uses ^, ~, >=, ||, hyphen ranges, and x-ranges. The package.json "dependencies" field supports all range types. Default save prefix is ^.
• Cargo (Rust): Uses ^ (default), ~, >=, and comma-separated requirements. ^1.2 is equivalent to >=1.2.0, <2.0.0. Wildcard uses *: 1.* matches all 1.x versions.
• Composer (PHP): Uses ^, ~, comparison operators, spaces as AND, || as OR. ~1.2 means >=1.2.0 <2.0.0 (differs from npm tilde). Supports branch aliases and stability flags (@dev, @beta).
• pip (Python via PEP 440): Uses ~= for compatible release (~=1.2 is >=1.2, ==1.*), and standard comparison operators. Python versioning extends beyond strict SemVer with epoch segments and local versions.
• Go modules: Enforces import compatibility rule — if MAJOR changes, the import path changes (e.g., v2 suffix). Range selection is implicit through Minimum Version Selection (MVS).

This tool supports the npm/node-semver range syntax as its primary comparison engine, which covers caret, tilde, comparison operators, OR chains, hyphen ranges, and wildcard ranges — the most expressive and widely-used range notation in the ecosystem.

Code Examples

Comparing versions and checking range satisfaction

import semver from 'semver';

// Basic comparison
semver.gt('2.1.0', '2.0.9');   // true  — 2.1.0 is greater
semver.lt('1.0.0-alpha', '1.0.0'); // true — pre-release < release
semver.eq('1.2.3', '1.2.3');   // true  — exact match

// Range satisfaction
semver.satisfies('1.4.2', '^1.2.0');  // true  — ^1.2.0 allows >=1.2.0 <2.0.0
semver.satisfies('2.0.0', '^1.2.0');  // false — 2.0.0 is outside ^1.2.0
semver.satisfies('1.2.5', '~1.2.3');  // true  — ~1.2.3 allows >=1.2.3 <1.3.0
semver.satisfies('1.3.0', '~1.2.3');  // false — 1.3.0 is outside tilde range

// Complex ranges with OR
semver.satisfies('3.1.0', '>=2.0.0 <3.0.0 || >=3.1.0');  // true

// Sorting versions
const versions = ['1.10.0', '1.9.0', '1.2.0', '2.0.0-beta', '2.0.0'];
semver.sort(versions);
// → ['1.2.0', '1.9.0', '1.10.0', '2.0.0-beta', '2.0.0']

// Finding max satisfying version from a list
semver.maxSatisfying(versions, '^1.0.0');  // '1.10.0'

Standards & Specifications

• Semantic Versioning 2.0.0 — The authoritative specification defining MAJOR.MINOR.PATCH format, precedence rules, and pre-release semantics
• node-semver — Reference implementation for SemVer range parsing used by npm, Yarn, and this tool