Was ist Semantic Versioning (Semver)? So lesen Sie X.Y.Z

Sie aktualisieren ein Paket und Ihr Team braucht eine schnelle Antwort. Bricht dieses Update den Build? Genau dafür gibt es Semantic Versioning. Die Methode verwandelt eine Versionsnummer in eine Nachricht. Paketmanager wie npm, pnpm und yarn lösen Abhängigkeiten ebenfalls nach dieser Konvention auf.

Was ist Semantic Versioning?

Semantic Versioning ist eine Nummerierungskonvention für Softwarepakete. Sie teilt eine Versionsnummer in drei Teile und zeigt den Umfang jeder Änderung konsistent an. Das Muster X.Y.Z steht für Major, Minor und Patch, in dieser Reihenfolge. Zudem verweist jede Zahl auf eine andere Art von Änderung.

Semver.org veröffentlicht die offizielle Spezifikation. Die Kurzform "Semver" bezieht sich auf genau dieses Dokument. Die Spezifikation bindet jede Versionserhöhung an eine klare Regel, nicht an Gewohnheit oder Vermutung. Dadurch kommen zwei Teams, die dieselbe Nummer lesen, zum gleichen Ergebnis.

Die Spezifikation definiert außerdem eine "öffentliche API". Zum Beispiel gehören dokumentierte Funktionen, Datentypen und Verhalten zu diesem Bereich. Interner Code darf sich frei ändern, solange diese öffentliche Oberfläche gleich bleibt. Semantic Versioning zählt eine solche interne Änderung dann nicht als Versionsänderung.

Teams diskutieren manchmal, ob eine Änderung als Minor oder Patch zählt. Die Spezifikation bietet dafür einen einfachen Test. Konkret gefragt: Läuft bestehender Code, der das Paket nutzt, ohne Anpassung weiter? Bei einem Ja zählt die Änderung höchstens als Minor. Sonst zählt sie als Major.

Wie Lesen Sie eine X.Y.Z Versionsnummer?

Im Muster X.Y.Z steht X für Major, Y für Minor und Z für Patch. Die Reihenfolge läuft von links nach rechts nach Wichtigkeit. Nehmen Sie Version 2.4.1 als Beispiel: Major ist 2, Minor ist 4 und Patch ist 1. Zusammengefasst fassen diese drei Zahlen die Änderungsgeschichte des Pakets zusammen.

Jede Zahl setzt sich auf null zurück, sobald eine Zahl links davon steigt. Erstens setzt ein Major Sprung Minor und Patch zurück. Zweitens setzt ein Minor Sprung nur Patch zurück. Dank dieser Regel muss ein Leser vergangene Änderungen nie erneut nachzählen.

Ein Entwickler erkennt oft schon an den Zahlen, welches Paket kürzlich eine größere Überarbeitung durchlief. Andere Pakete blieben dagegen ruhig. Diese Lesefähigkeit wird mit der Zeit so selbstverständlich wie das Lesen eines Diffs.

• X (Major): rückwärts inkompatible, kritische Änderungen.
• Y (Minor): rückwärts kompatible neue Funktionen.
• Z (Patch): rückwärts kompatible Fehlerbehebungen.

Wann Steigt die Major Version?

Die Major Version steigt, sobald eine Änderung die öffentliche API bricht. Die Spezifikation sagt das klar. Ändert sich das Verhalten, ein Parameter oder ein Rückgabewert einer bestehenden Funktion und bricht dadurch ein Projekt mit altem Code, zählt das als Major Änderung.

Ein Major Sprung ist zugleich ein Warnsignal. Zunächst lesen Sie vor dem Update die Release Notes. Danach prüfen Sie außerdem Ihren eigenen Code auf Konflikte. Deshalb planen Teams einen Major Sprung meist in ein festes Wartungsfenster, statt ihn automatisch zu laden.

Ein Maintainer kündigt einen kommenden Bruch oft früh an. Zunächst markiert er eine Funktion als veraltet. Erst später, in einem künftigen Major Release, entfernt er sie tatsächlich. Dieser zweistufige Weg gibt nutzenden Teams Zeit zur Vorbereitung.

Ein Paket kann mehrere Dinge gleichzeitig ändern. Trotzdem steigt die Major Zahl nur um eins. Semantic Versioning beantwortet eine einzige Frage: welche Änderung wiegt hier am schwersten? Eine einzige kritische Änderung neben zehn kleinen Korrekturen erzwingt also ein Major Release.

Wann Steigt die Minor Version?

Die Minor Version steigt, wenn ein Maintainer eine rückwärts kompatible Funktion hinzufügt. Bestehender Code läuft ohne Anpassung weiter. Stattdessen steht eine neue Option oder Funktion einfach zusätzlich zur Verfügung.

Die Spezifikation verlangt auch dann einen Minor Sprung, sobald ein Maintainer eine Funktion als veraltet markiert. Konkret warnt dieser Schritt Nutzende, ohne etwas zu brechen. Maintainer bündeln ebenso größere interne Verbesserungen oft in einem Minor Release und beschreiben sie in denselben Notizen.

Stellen Sie sich eine Bibliothek vor, die in Version 2.3.0 eine neue Konfigurationsoption liefert. Ein Projekt, das diese Option ignoriert, läuft genau wie vorher weiter. Nur das Team, das das neue Verhalten will, liest die Dokumentation und nutzt die Option.

Wann Steigt die Patch Version?

Die Patch Version steigt bei einer rückwärts kompatiblen Fehlerbehebung. Konkret definiert die Spezifikation eine Fehlerbehebung als interne Änderung, die falsches Verhalten korrigiert. Die sichtbare API bleibt dabei gleich. Stattdessen verschwindet nur das unerwartete Verhalten.

Die meisten Teams halten Patch Releases für die sicherste Art von Update. Per Definition fügt ein Patch keine neue Funktion hinzu und ändert keine bestehende Nutzung. Deshalb lassen viele Teams Patch Updates automatisch durch, mit höchstens einer kurzen Prüfung.

Ein Sprung von 1.2.5 auf 1.2.6 behebt meist nur einen Fehler. In diesem Fall lässt ein Team das Update ohne manuelle Prüfung durch. Allerdings bricht ein als "Patch" markiertes Release, das leise das Verhalten ändert, den Semver Vertrag.

Was Bedeutet eine 0.y.z Version?

Die Spezifikation nennt den Bereich 0.y.z "initiale Entwicklung". Konkret kann sich alles in dieser Phase jederzeit ändern. Solange ein Paket bei 0.y.z liegt, hat seine öffentliche API noch keinen stabilen Zustand erreicht.

In dieser Phase liest ein Team Minor und Patch Sprünge nicht wie nach 1.0.0. Der Maintainer hat noch kein Stabilitätsversprechen abgegeben. Deshalb beobachten Sie das Veröffentlichungstempo einer 0.y.z Abhängigkeit genau, bevor Sie sie in die Produktion bringen.

Viele neue Open Source Projekte bleiben absichtlich bei 0.y.z. Stattdessen wollen sie zuerst frühes Feedback sammeln. Der Maintainer behandelt jedes Release als mögliche kritische Änderung und schreibt das klar in die Dokumentation.

Warum Zählt der Übergang zu 1.0.0?

Version 1.0.0 markiert den Punkt, an dem die öffentliche API feststeht. Ab diesem Moment beginnt also ein echtes Stabilitätsversprechen. Von dieser Version an bewertet die Spezifikation jede Änderung nach den Major, Minor oder Patch Regeln.

Ein Projekt, das von einem Paket vor 1.0.0 abhängt, sollte bei jedem Update ein geändertes Verhalten erwarten. Nach 1.0.0 dürfen Entwickler meist etwas anderes annehmen. Updates mit derselben Major Zahl sollten die API nicht brechen.

Dieser Übergang verschiebt auch die Verantwortung. Der Maintainer verpflichtet sich nun, jede kritische Änderung über einen Major Sprung anzukündigen. Ohne diese Zusage können Nutzende der Nummer nicht trauen. Stattdessen testen sie jedes Update von Grund auf neu.

Was Bedeuten Vorab Versionen (Alpha, Beta, RC) bei Semantic Versioning?

Eine Vorab Version ist eine Reihe von punktgetrennten Kennungen. Sie hängen diese direkt nach der Patch Zahl mit einem Bindestrich an, etwa 1.0.0-alpha.1. Die Spezifikation verlangt die Worte Alpha, Beta oder RC nicht. Das sind also nur gängige, gültige Beispiele.

Eine Vorab Version zeigt, dass ein Release noch nicht stabil ist. Schließlich kann sich das Release jederzeit noch ändern. Kennungen dürfen nur ASCII Buchstaben, Ziffern und Bindestriche enthalten. Sie dürfen nicht leer sein, und eine numerische Kennung darf keine führende Null tragen.

Viele Teams folgen einer gängigen Reihenfolge. Alpha markiert die früheste, am wenigsten stabile Stufe. Beta folgt, sobald der Funktionsumfang steht, aber Tests noch laufen. RC, kurz für Release Candidate, markiert schließlich die letzte Prüfung vor dem stabilen Release. Die Spezifikation selbst erzwingt diese Reihenfolge nicht.

Wie Ordnen Sie Vorab Versionsnummern?

Eine Vorab Version steht immer unter der normalen Version mit derselben Kernzahl. Also steht 1.0.0-beta immer unter 1.0.0. Beim Vergleich zweier Vorab Versionen vergleichen Sie die Kennungen eine nach der anderen, von links nach rechts.

Numerische Kennungen vergleichen Sie numerisch. Jede andere Kennung vergleichen Sie dagegen in ASCII Reihenfolge. Eine numerische Kennung steht immer unter einer Kennung mit Buchstaben. Die eigene Beispielreihenfolge der Spezifikation lautet so: 1.0.0-alpha, dann 1.0.0-alpha.1, dann 1.0.0-alpha.beta, dann 1.0.0-beta, dann 1.0.0-beta.2, dann 1.0.0-beta.11, dann 1.0.0-rc.1 und schließlich 1.0.0.

Diese Reihenfolge zählt in der Praxis. Ein Paketmanager stützt sich darauf, um die "neueste" Vorab Version korrekt zu wählen. Ein Bereich wie ^1.0.0-alpha hängt genau von diesen Vergleichsregeln ab.

Was ist Build Metadata?

Build Metadata ist eine zusätzliche Information an einer Version. Sie fügen diese mit einem Pluszeichen und punktgetrennten Kennungen an, etwa 1.0.0+20130313144700. Zum Beispiel trägt dieses Feld häufig einen Build Zeitstempel oder eine Commit Kennung.

Die Spezifikation sagt Ihnen, Build Metadata beim Vorrangvergleich zu ignorieren. Deshalb haben 1.0.0+a und 1.0.0+b den gleichen Vorrang. Der Unterschied steckt nur im zusätzlichen Label. Er ändert also nie die Versionsreihenfolge.

Teams nutzen Build Metadata oft zur internen Nachverfolgung. Zum Beispiel kann es festhalten, welche Build Maschine ein bestimmtes Paket erzeugt hat. Nutzende sehen dieses Label, allerdings steuert es allein keine Update Entscheidung.

Wie Nutzen CI/CD Pipelines Semantic Versioning?

Eine Release Pipeline entscheidet automatisch, welchen Teil der Version sie erhöht. Sie scannt Commit Nachrichten oder Tags, bevor sie ein neues Release schneidet. Konkret lesen viele Werkzeuge einen "fix:" Commit als Patch. Ein "feat:" Commit wird zu Minor, und jeder Commit mit "BREAKING CHANGE" wird zu Major.

Diese Automatisierung nimmt dem Prozess etwas menschlichen Fehler. Deshalb wählt das Team die Nummer nicht mehr bei jedem Release selbst. Trotzdem liest das Werkzeug nur Commit Nachrichten; es versteht den Code selbst nicht. Die Commit Nachricht des Entwicklers muss die Änderung also weiterhin richtig einordnen.

Ein Prüfschritt vor dem Release hilft hier zusätzlich. Dieser Schritt fängt Fälle ab, in denen eine automatische Erhöhung einen Commit falsch liest und die falsche Nummer erzeugt. Dadurch behält das Team die Geschwindigkeit der Automatisierung, ohne die Verlässlichkeit zu verlieren.

Wie Funktionieren Versionsbereiche in package.json?

Eine Abhängigkeitszeile in package.json nennt meist einen Bereich, keine feste Version. So kann der Paketmanager also die neueste passende Version wählen. Die offizielle npm Dokumentation definiert diese Bereiche mit Zeichen wie Tilde und Caret.

Einen Bereich einmal zu schreiben, erspart dem Team das manuelle Bearbeiten von package.json bei jedem Update. Stattdessen hält der Paketmanager die genau installierte Version in einer Lock Datei neben diesem Bereich fest.

Vor der Wahl wägt ein Team erst ab, wie verlässlich eine Abhängigkeit Releases veröffentlicht. Zum Beispiel funktioniert ein Caret Bereich oft gut für ein Paket, das Semver strikt folgt. Ein selteneres Release Tempo oder eine Geschichte voller gebrochenem Semver verlangt dagegen einen engeren Bereich.

Was Bedeutet das Caret (^) Zeichen?

Die npm Dokumentation beschreibt das Caret Zeichen als Bereich für Minor Updates. ^1.0.4 akzeptiert jede Version im Bereich 1.x.x. Es stoppt vor 2.0.0. Konkret setzt dieser Bereich voraus, dass die Major Zahl fest bleibt.

Viele Projekte wählen Caret als Standardbereich. Schließlich verspricht Semantic Versioning, dass Updates mit derselben Major Zahl die API nicht brechen. Das Verhalten von Caret ändert sich allerdings bei 0.y.z Paketen. Dort prüfen Sie also Release Notes besser direkt.

Schreiben Sie zum Beispiel ^0.4.2. npm wendet hier eine Sonderregel für Null Major Versionen an. Sie bleiben in 0.4.x, statt zu 0.5.0 zu springen, weil eine Minor Zahl innerhalb von 0.y.z noch kein Stabilitätsversprechen trägt. Dieses Detail überrascht viele Teams.

Was Bedeutet das Tilde (~) Zeichen?

Die npm Dokumentation beschreibt Tilde als engeren Bereich für reine Patch Updates. Es akzeptiert nur Versionen im Bereich 2.2.x bei ~2.2.0. Vor allem spielt diese Wahl insgesamt vorsichtiger als Caret.

Teams greifen zu Tilde, wenn sie selbst Minor Änderungen einer Abhängigkeit nicht trauen. So lässt die Automatisierung weiterhin Fehlerbehebungen durch. Zudem bleiben neue Funktionen außen vor, bis jemand sie manuell prüft.

Systeme mit geringer Fehlertoleranz, etwa im Finanz oder Gesundheitsbereich, wählen Tilde oft als Standard. Dort zählt eine unerwartete Minor Änderung schließlich als nicht akzeptables Risiko. Das Team leitet deshalb jede neue Funktion durch einen eigenen Prüfschritt.

Manche Teams verfolgen beides zugleich, Tempo und Sicherheit. Sie mischen stattdessen die Bereiche: Tilde für kritische Abhängigkeiten, Caret für Helfer mit geringerem Risiko. Diese gemischte Strategie passt das Risiko an jede Abhängigkeit einzeln an, statt überall dieselbe Regel zu nutzen.

Wie Erleichtert Semantic Versioning die Abhängigkeitsverwaltung?

Diese Konvention lässt ein Team die Sicherheit eines Updates allein an der Versionsnummer ablesen. Jeder Paketmanager kann deshalb eine Bereichsregel festlegen. Anschließend automatisiert er die Updates, die keine menschliche Freigabe brauchen.

Sobald ein Projekt Dutzende Abhängigkeiten hat, bleibt die manuelle Kontrolle jeder einzelnen unpraktisch. Semantic Versioning ändert das. Das Team reserviert die manuelle Prüfung für Major Änderungen und automatisiert den Rest mit Vertrauen.

Viele Sicherheitsscanner stützen sich auf dieselbe Regel. Findet ein Scanner eine Schwachstelle, empfiehlt er die niedrigste Patch Version, die sie behebt. Dadurch schließt das Team die Lücke schnell, ohne einen Major Sprung zu wagen.

Was Läuft in Projekten Schief, die Semantic Versioning Ignorieren?

Ein Paket, das Semver Regeln ignoriert, macht seine Versionsnummer zu reinem Rauschen. Nutzende raten dann bei jedem Update, statt der Nummer zu trauen. Ein als "Patch" markiertes Release kann leise die API brechen, was automatische Updates riskant macht.

Teams in dieser Lage fixieren die Abhängigkeit meist auf eine feste Version. Sie testen dann jedes Update manuell. Allerdings kostet diese Wahl den Automatisierungsvorteil von Semantic Versioning, und sie bringt echten Wartungsaufwand mit sich.

Manche Teams gleichen dieses Risiko anders aus. Sie erweitern ihre automatische Testsuite, damit sie bei jedem Abhängigkeitssprung jeden kritischen Pfad prüft. Dieser Ansatz ersetzt Semvers Garantie nicht, aber er begrenzt den Schaden.

Wie Wenden Sie Semantic Versioning in einem Monorepo An?

Ein Repository mit mehreren Paketen hat zwei Optionen. Konkret trägt jedes Paket seine eigene X.Y.Z Zahl, oder alle Pakete bewegen sich gemeinsam unter einer geteilten Version. Der geteilte Ansatz hält die Kompatibilität zwischen Paketen einfach, erhöht aber jedes Paket schon bei einer kleinen Änderung.

Ein Workspace fähiger Paketmanager geht anders vor. Er verfolgt über ein eigenes Workspace Protokoll, welchen Versionsbereich eine interne Abhängigkeit nutzt. So vermeiden Pakete im Monorepo, sich bei jeder Veröffentlichung neu herunterzuladen.

1. Entscheiden Sie früh, ob jedes Paket eine eigene Version erhält oder eine teilt.
2. Verweisen Sie interne Abhängigkeiten auf das Workspace Protokoll, nicht auf eine feste Versionsnummer.
3. Sammeln Sie die Release Notes aller Pakete vor jeder Veröffentlichung in einer Liste.

Welche Fehler Machen Teams bei Semantic Versioning?

Der häufigste Fehler behandelt eine Änderung als "nur Patch", obwohl sie tatsächlich die API bricht. Das Team veröffentlicht sie dann ohne Minor oder Major Sprung. Folglich trifft genau dieser Fehler jedes nachgelagerte Projekt, das dem Bereich vertraut.

Ein zweiter Fehler mischt Vorab Versionen uneinheitlich. Ein Release nutzt Alpha, das nächste Beta, ohne klaren Qualitätsunterschied dazwischen. Regelmäßig aktualisierte Release Notes verhindern die meisten dieser Fehler.

Ein dritter Fehler überspringt das Changelog ganz und schätzt das Risiko allein an der Nummer ab. Schließlich zeigt die Nummer nur die Art der Änderung, nicht ihre Details. Das Changelog zu lesen, zeigt dagegen das wahre Risiko, besonders rund um Major Releases.

• Listen Sie vor jedem Release genau, was in der öffentlichen API sich ändert.
• Erhöhen Sie die Major Version bei jeder kritischen Änderung, auch bei einer kleinen.
• Nutzen Sie Vorab Versionen (Alpha, Beta, RC) in einer einheitlichen Reihenfolge.

Welche Werkzeuge Prüfen Semantic Versioning Automatisch?

Viele Entwicklungsumgebungen vergleichen ein neues Release automatisch mit dem vorherigen. Das Werkzeug markiert dabei selbst eine kritische Änderung in der öffentlichen API. Zudem erkennt es eine geänderte Funktionssignatur sogar dann, wenn ein Entwickler das Release versehentlich als "Patch" markiert hat.

Diese Prüfung findet kleine, aber kritische Änderungen, die ein menschlicher Blick leicht übersieht. Das zählt vor allem bei einer Bibliothek mit großer API Oberfläche, wo manuelle Prüfung nicht mehr skaliert. Ein Team, das diese Prüfung in die Pipeline einbaut, stoppt ein fehlerhaftes Release, bevor es die Produktion erreicht.

Wie Wählen Sie die Erste Versionsnummer einer Bibliothek?

Ein Entwickler startet ein neues Paket meist bei 0.1.0. Diese Wahl hält die Tür für Änderungen offen, noch ohne Stabilitätsversprechen. Andererseits starten manche Maintainer direkt bei 1.0.0. Das sendet von Anfang an eine klare Botschaft: diese API bleibt stabil.

Welche Wahl Sie auch treffen, schreiben Sie sie klar in Ihre Dokumentation. Sonst erkennt ein Nutzer nicht, ob ein Paket bei 0.y.z liegt oder 1.0.0 schon hinter sich hat. In diesem Fall kann er sich nicht voll auf Semvers übliche Garantie verlassen.

Viele Maintainer setzen genau deshalb ein kleines Badge oben in die README. Ein Entwickler, der das Paket prüft, sieht dann sofort die Stabilitätsstufe. Ebenso erreicht ein neues Teammitglied dieselbe Information innerhalb von Sekunden.

Wie Hängt Semantic Versioning mit dem Changelog Zusammen?

Eine Versionsnummer zeigt die Art einer Änderung, nicht ihren Inhalt. Konkret schließt ein Changelog genau diese Lücke. Schreibt ein Maintainer bei jedem Release eine kurze Notiz, wird die Bedeutung der Nummer konkret.

Ein Projekt mit aktuellem Changelog hilft Nutzenden bei einer schnellen Entscheidung. Sie beantworten "soll ich dieses Update jetzt holen" ohne nur auf die Nummer zu starren. Kombinieren Sie Semantic Versioning mit einem Changelog, verwaltet ein Team automatische und manuell geprüfte Updates in einem einzigen Ablauf.

Ein guter Changelog Eintrag beantwortet drei Fragen. Erstens: was hat sich geändert? Zweitens: wen betrifft es? Schließlich: wie wechseln Sie dorthin? Ein Eintrag, der alle drei Fragen abdeckt, macht aus dem kurzen Signal der Nummer einen konkreten Handlungsplan.

Wie Ergänzt eine Lock Datei Semantic Versioning?

Ein Bereich in package.json legt fest, welche Versionen akzeptabel sind. Zudem geht eine Lock Datei weiter. Sie fixiert die genau installierte Version aus diesem Bereich. Zusammen garantieren beide, dass ein Projekt überall denselben Abhängigkeitsbaum nutzt.

Ohne Lock Datei können zwei Entwickler mit demselben Caret Bereich trotzdem auseinanderlaufen. Einer bekommt an einem anderen Tag eine andere Patch oder Minor Version. Diese kleine Lücke zählt vor allem deshalb, weil manche Fehler nur in einer bestimmten Version auftauchen.

Sobald ein Team seine Lock Datei ins Repository aufnimmt, ändert sich das Bild. Der Server und jeder Entwicklerrechner bauen nun denselben Abhängigkeitsbaum. Diese Konsistenz macht Semvers Versprechen zu einer praktischen Garantie beim Deployment.

Welche Verwandten Themen Sollten Sie Auch Prüfen?

Das richtige Auflösen von Versionsbereichen hängt auch von einer konsistenten Entwicklungsumgebung ab. Teams unter Windows starten gut mit unserem Leitfaden zu was WSL2 ist. Teams, die lieber Container nutzen, lesen stattdessen unseren Leitfaden zum VS Code Dev Container. Unter Apple Silicon ist unser Beitrag dazu, wann Sie Rosetta brauchen, ebenfalls verwandt.

Auf der Linux Seite deckt unser Leitfaden zur Wahl eines Linux Mirrors eine ähnliche Zuverlässigkeitsfrage ab. Für die Designprinzipien hinter einer stabilen öffentlichen API lesen Sie unseren Leitfaden zu SOLID Prinzipien. Für einen geordneten Release Kalender im Team lesen Sie stattdessen unseren Leitfaden zu Projektmanagement Tools für Entwickler; beide sind Schwesterthemen dieser Reihe. Wenn ESLint und Prettier Konfigurationen sich widersprechen, behandeln wir diesen Konflikt in einem eigenen Beitrag.

Unser Leitfaden dazu, wie sich pnpm von npm und yarn unterscheidet, geht tiefer auf die Paketmanagerwahl ein. Unser Leitfaden zum npm ERESOLVE Fehler hilft stattdessen, wenn die Abhängigkeitsauflösung stockt. Bei individuellen Softwareprojekten verfolgt unser Team bei der individuellen Softwareentwicklung Abhängigkeitsversionen nach genau dieser Konvention.

Die vollständige Spezifikation lesen Sie bei semver.org. Die eigene Bereichssyntax von npm lesen Sie außerdem in der offiziellen npm Dokumentation.