Semantic Versioning
Semantic Versioning (SemVer)
Semantic Versioning (kurz SemVer) ist ein Schema zur Versionsnummerierung von Software, das aus einer Versionsnummer MAJOR.MINOR.PATCH besteht. Ziel ist, aus der Versionsnummer zuverlässig abzuleiten, ob ein Update abwärtskompatibel ist und welche Art von Änderungen enthalten sind.
Grundidee
Eine Version besteht aus drei Zahlen:
- MAJOR – Inkompatible/Breaking Änderungen (API-Bruch)
- MINOR – Neue Features, abwärtskompatibel
- PATCH – Bugfixes, abwärtskompatibel
Beispiel: 2.4.1
- MAJOR = 2
- MINOR = 4
- PATCH = 1
Regeln
1) MAJOR erhöhen
Erhöhe MAJOR, wenn du breaking changes einführst, also eine Änderung, die bestehende Nutzer/Integrationen bricht (z. B. entfernte/umbenannte API-Endpunkte, geänderte Parameter, geänderte Rückgabeformate).
Beispiele:
- Entfernen eines REST-Endpunkts
- Änderung von Pflichtfeldern in einem JSON-Request
- Umbenennen einer öffentlichen Funktion/Klasse
2) MINOR erhöhen
Erhöhe MINOR, wenn du neue Funktionalität hinzufügst, die abwärtskompatibel ist.
Beispiele:
- Neuer optionaler Parameter
- Neuer API-Endpunkt, der bestehende nicht verändert
- Zusätzliche Felder in einer Response (sofern Clients robust sind)
3) PATCH erhöhen
Erhöhe PATCH, wenn du Bugfixes oder interne Korrekturen veröffentlichst, ohne neue Features und ohne Breaking Changes.
Beispiele:
- Fix eines Nullpointer/Exceptions
- Korrektur eines Berechnungsfehlers
- Security-Fix ohne API-Änderung
Pre-Release und Build-Metadaten
SemVer erlaubt Erweiterungen:
Pre-Release
Format: MAJOR.MINOR.PATCH-<label> Pre-Releases sind instabil und haben eine niedrigere Priorität als die zugehörige Release-Version.
Beispiele:
- 1.2.0-alpha
- 1.2.0-alpha.1
- 1.2.0-beta
- 1.2.0-rc.1
Build-Metadaten
Format: MAJOR.MINOR.PATCH+<build> Build-Metadaten beeinflussen nicht die Versions-Priorität.
Beispiele:
- 1.2.3+20260127
- 1.2.3+git.abc123
Vergleich (Priorität)
Die Reihenfolge richtet sich nach MAJOR, dann MINOR, dann PATCH.
- 1.0.0 < 2.0.0
- 1.2.0 < 1.3.0
- 1.2.3 < 1.2.4
Pre-Releases sind kleiner als das Release:
- 1.2.0-alpha < 1.2.0
- 1.2.0-rc.1 < 1.2.0
Was gilt als „API“?
In SemVer ist die Definition deiner öffentlichen API zentral. Als API zählt alles, worauf Nutzer/andere Systeme sich verlassen:
- Öffentliche Funktionen/Klassen/Methoden
- CLI-Parameter und Exit-Codes
- REST-/GraphQL-Endpunkte, Request/Response-Schemas
- Events, Message-Formate, Daten*