SemVer-Validator: Format der semantischen Versionierung prüfen

Was ist Semantic Versioning?

Semantic Versioning (SemVer) ist ein Versionierungsschema, das jedem Teil einer Versionsnummer eine Bedeutung zuweist. SemVer wurde von Tom Preston-Werner entwickelt und bietet eine universelle Konvention, um Art und Auswirkung von Software-Änderungen allein über die Versionsnummer zu kommunizieren.

Durch die Einhaltung von SemVer können Entwickler und Nutzer sofort erkennen, ob ein Update Breaking Changes, neue Funktionen oder Fehlerbehebungen mit sich bringt – einfach durch das Lesen der Versionsnummer. Diese Vorhersehbarkeit ist für das Abhängigkeitsmanagement in modernen Software-Ökosystemen entscheidend.

Das SemVer-Format

Eine semantische Version besteht aus drei durch Punkte getrennten numerischen Komponenten: MAJOR.MINOR.PATCH.

• MAJOR – wird erhöht, wenn du inkompatible API-Änderungen vornimmst. Der Wechsel von 1.x.x zu 2.0.0 signalisiert, dass bestehender Code brechen kann
• MINOR – wird erhöht, wenn du Funktionen auf abwärtskompatible Weise hinzufügst. Der Wechsel von 1.2.x zu 1.3.0 bedeutet neue Funktionen, ohne bestehende zu brechen
• PATCH – wird erhöht, wenn du abwärtskompatible Fehlerbehebungen vornimmst. Der Wechsel von 1.2.3 zu 1.2.4 bedeutet, dass nur Fehler behoben wurden
• Jede Komponente muss eine nicht negative Ganzzahl sein und darf keine führenden Nullen enthalten (1.02.3 ist ungültig)

Versionsbereiche und Einschränkungen

Paketmanager verwenden Versionsbereiche, um kompatible Abhängigkeitsversionen anzugeben. Diese Bereiche zu verstehen ist für zuverlässige Builds unerlässlich.

• Caret-Bereiche (^1.2.3) – erlauben Änderungen, die die am weitesten links stehende Ziffer ungleich null nicht verändern. ^1.2.3 bedeutet jede Version ab 1.2.3 bis ausschließlich 2.0.0
• Tilde-Bereiche (~1.2.3) – erlauben nur Änderungen auf Patch-Ebene. ~1.2.3 bedeutet jede Version ab 1.2.3 bis ausschließlich 1.3.0
• Exakte Version (1.2.3) – nur genau diese Version ist zulässig, ohne jede Flexibilität

Häufige Anwendungsfälle

Semantic Versioning ist die Grundlage moderner Paketverwaltung und Release-Workflows.

• npm, pip und Cargo – Paketmanager verlassen sich auf SemVer, um Abhängigkeitsbäume aufzulösen und zu verhindern, dass Breaking Changes in die Produktion gelangen
• CI/CD-Pipelines – automatisierte Systeme nutzen SemVer-Tags, um Builds auszulösen, Releases zu veröffentlichen und Changelogs zu erzeugen
• API-Versionierung – REST-APIs verwenden Major-Versionen in URLs (v1, v2), um die Abwärtskompatibilität zu wahren, während sie weiterentwickelt werden
• Bibliotheksautoren – die Veröffentlichung einer Bibliothek mit korrektem SemVer signalisiert den Nutzern, wann Upgrades sicher sind

Pre-Release- und Build-Metadaten

SemVer unterstützt zwei optionale Erweiterungen, die Versionsnummern Kontext hinzufügen, ohne die Regeln zur Reihenfolge zu beeinflussen.

• Pre-Release-Bezeichner – werden nach einem Bindestrich angehängt: 1.0.0-alpha, 1.0.0-beta.2, 1.0.0-rc.1. Sie kennzeichnen Versionen, die noch nicht stabil sind, und haben eine niedrigere Priorität als das zugehörige Release
• Build-Metadaten – werden nach einem Pluszeichen angehängt: 1.0.0+build.123, 1.0.0-beta+exp.sha.5114f85. Build-Metadaten werden bei der Bestimmung der Versionsreihenfolge ignoriert
• Pre-Release-Versionen werden anhand punktgetrennter Bezeichner sortiert: numerische Bezeichner werden numerisch sortiert, alphanumerische Bezeichner lexikalisch

Häufig gestellte Fragen

Wird 0.x.x anders behandelt als 1.x.x?

Ja. In SemVer kennzeichnet die Version 0.x.x eine frühe Entwicklungsphase, in der sich jederzeit alles ändern kann. Die öffentliche API sollte nicht als stabil betrachtet werden. Sobald du 1.0.0 veröffentlichst, verpflichtest du dich, die SemVer-Regeln für alle folgenden Releases einzuhalten.

Kann ich v als Präfix verwenden (v1.2.3)?

Die SemVer-Spezifikation enthält kein v-Präfix – das kanonische Format ist 1.2.3. Viele Tools (Git-Tags, GitHub-Releases) verwenden jedoch üblicherweise v1.2.3. Die meisten Validatoren akzeptieren beide Formen.

Was passiert, wenn ich vergesse, bei einem Breaking Change die Major-Version zu erhöhen?

Nutzer, die Caret-Bereiche verwenden, erhalten das Update automatisch, und ihre Builds können unerwartet brechen. Deshalb ist SemVer-Disziplin so wichtig – sie ist ein sozialer Vertrag zwischen Bibliotheksautoren und Nutzern.