Semantic Versioning und dein Changelog

Semantic Versioning sagt einer Aufruferin, wie sehr ein Release ihr wehtun kann, bevor sie einen einzigen Changelog-Eintrag gelesen hat. Von 2.4.1 auf 2.5.0 heißt: neue Fähigkeit, nichts bricht. Von 2.5.0 auf 3.0.0 heißt: diesen Eintrag vor dem Update lesen. Changelog und Versionsnummer sollen dieselbe Aussage in zwei Formaten treffen, und die meisten Reibungen zwischen beiden zeigen sich genau dann, wenn sie sich widersprechen, was öfter passiert, als die Spezifikation es nahelegt.

Was verspricht jede Zahl in einer Version eigentlich?

Semantic Versioning definiert drei Zahlen, MAJOR.MINOR.PATCH, jede mit einer strengen Regel dafür, was sie auslöst. Ein Major-Sprung bedeutet eine Breaking Change: etwas, das eine korrekte, bestehende Integration bemerken könnte und weswegen sie sich ändern müsste. Ein Minor-Sprung bedeutet neue, abwärtskompatible Funktionalität: Nichts Bestehendes bricht, etwas Neues ist verfügbar. Ein Patch-Sprung bedeutet einen abwärtskompatiblen Bugfix: Verhalten kommt näher an das heran, was dokumentiert war, und niemand, der sich absichtlich auf das alte Verhalten verlassen hat, sollte etwas bemerken.

Die Tabelle ist auch rückwärts ein Test: Klingt ein Eintrag nicht wie seine Zeile, ist entweder die Versionsnummer falsch, oder der Eintrag verkauft das Ereignis zu klein oder zu groß.

Was zählt für Versionierungszwecke als Breaking Change?

Derselbe Test, der entscheidet, ob etwas überhaupt in ein API-Changelog gehört: Könnte eine korrekte Aufruferin, geschrieben gegen das alte Verhalten und seither unverändert, sich wegen dieser Änderung anders verhalten. Was ist eine Breaking Change, und wie liefert man sie aus behandelt die Entscheidung vollständig, samt der Fälle, die brechend aussehen und es nicht sind, und denen, die klein aussehen und es nicht sind. Kurz für Versionierungszwecke: Lautet die Antwort ja, ist der Sprung Major, egal wie viel Code die Änderung intern tatsächlich berührt hat. Versionsnummern verfolgen die Konsequenz für die Aufruferin, nicht den Aufwand für das Team.

Wie sollte ein Changelog-Eintrag zu einem Versionssprung passen?

Ein Eintrag, eine Sprungkategorie, gleich zu Beginn genannt. Das Muster aus der Tabelle setzt sich direkt fort: Ein brechender Eintrag steht unter der Version, die ihn eingeführt hat, formuliert erst als Warnung, dann als Beschreibung. Ein additiver Eintrag steht unter seiner Minor-Version, formuliert als Verfügbarkeit. Ein Fix steht unter seiner Patch-Version, formuliert als Korrektur. Kategorien in einem Eintrag zu mischen, etwa eine Breaking Change in denselben Absatz wie einen unabhängigen Fix zu falten, ist der Weg, wie eine Leserin genau das Eine verpasst, das wirklich zählte.

## 3.0.0 (2026-09-07)

### Changed
- **BREAKING:** `GET /reports` liefert Beträge jetzt als Ganzzahl in
  der kleinsten Währungseinheit (Cent) statt als Fließkommazahl. Code,
  der `amount` direkt liest, muss angepasst werden.

## 2.9.0 (2026-09-01)

### Added
- Reports lassen sich jetzt nach `status` filtern.

## 2.8.4 (2026-08-28)

### Fixed
- `GET /reports?status=` lieferte eine leere Seite statt eines 400 bei
  unbekanntem Status.

Von oben nach unten gelesen sagen Versionsnummer und Abschnittslabel dasselbe zweimal, und genau das ist der Zweck: Eine Leserin, die nur die Überschriften überfliegt, bekommt eine korrekte Risikoeinschätzung, bevor sie eine einzige Zeile öffnet.

Gilt die Breaking-Change-Regel vor 1.0.0 auf dieselbe Weise?

Nein, und genau daher kommt der meiste Streit darüber, was „wirklich brechend” war. SemVer sagt ausdrücklich, dass Hauptversion null, 0.y.z, für die initiale Entwicklung gedacht ist: Alles kann sich jederzeit ändern, und die öffentliche Schnittstelle sollte nicht als stabil gelten. Ein Sprung von 0.4.0 auf 0.5.0 kann eine Breaking Change enthalten, ohne die Spezifikation zu verletzen, weil das Major-Versionsversprechen erst greift, sobald ein Projekt 1.0.0 ausliefert. Ein Changelog-Eintrag schuldet Leserinnen trotzdem dieselbe Ehrlichkeit darüber, was gebrochen ist; was sich ändert, ist nur, dass die Versionsnummer selbst vor 1.0.0 nicht das Signal ist, auf das man sich verlassen sollte.

Was, wenn dein Produkt keine diskreten Versionen ausliefert?

Die meisten SaaS-Produkte deployen kontinuierlich und zeigen einer Aufruferin nie eine Versionsnummer, was die Notwendigkeit der Disziplin nicht aufhebt, nur die Zahl, die sie normalerweise trüge. Der Changelog-Eintrag muss die ganze Arbeit allein leisten: klar sagen, ob eine Änderung brechend, additiv oder ein Fix ist, mit denselben drei Wörtern, die auch Semantic Versioning benutzt, auch ohne Versionsfeld, an das man sie hängen könnte. Manche Teams pflegen eine rein interne Version, nur um Changelog-Einträge an etwas Verlinkbarem zu verankern, ohne sie je der Aufruferin direkt zu zeigen.

Wie gilt das speziell für ein API-Changelog?

Strenger als fast überall sonst, weil die Aufruferinnen einer API Code sind, keine Menschen, die eine unerwartete Änderung achselzuckend hinnehmen können. API-Changelog: was hinein gehört und wer es liest behandelt die volle Form dieses Dokuments; die Versionierungsdisziplin hier hält dessen Breaking- und Additive-Abschnitte ehrlich. Eine API, die mehrere Versionen parallel anbietet, etwa v1 und v2 gleichzeitig während eines Migrationsfensters, betreibt Semantic Versioning effektiv auf der Skala der gesamten Schnittstelle statt eines einzelnen Pakets, und dasselbe Drei-Wörter-Vokabular gilt weiterhin für jeden Eintrag.

Was sagt Keep a Changelog zur Versionierung?

Es verknüpft sich namentlich direkt mit Semantic Versioning und empfiehlt dasselbe Kategorien-Vokabular, das dieser Artikel verwendet: Added, Changed, Deprecated, Removed, Fixed, Security. Keep a Changelog, umgesetzt geht durch, wie man diese Spezifikation in der Praxis übernimmt, samt der Stellen, an denen Teams meist davon abweichen. Die Überschneidung ist kein Zufall: Beide Spezifikationen lösen dasselbe Problem von entgegengesetzten Enden, die eine standardisiert die Versionsnummer, die andere den Eintrag, der sie erklärt.

FAQ

Braucht jeder Changelog-Eintrag eine Versionsnummer? Wenn das Produkt Versionen ausliefert, ja, weil die Zahl einer Leserin erlaubt, direkt zu „wie sehr betrifft mich das” zu springen, ohne den Eintrag erst zu lesen. Deployt das Produkt kontinuierlich ohne Versionsfeld, muss die Formulierung des Eintrags dieses Signal allein tragen.

Was ist der Unterschied zwischen einem Major-Sprung und einem Breaking-Change-Eintrag? Sie sollten dasselbe Ereignis auf zwei Arten beschreiben. Die Versionsnummer ist das maschinenlesbare Signal (Tooling einer Aufruferin kann darauf reagieren); der Changelog-Eintrag ist die menschenlesbare Erklärung, was konkret sich geändert hat.

Kann ein Patch-Release brechend sein? Per Definition sollte es nicht. Wurde doch eines ausgeliefert, bearbeitet oder taggt die veröffentlichte Version nicht neu: Die SemVer-FAQ sagt, eine neue Version zu veröffentlichen, die die Kompatibilität wiederherstellt, oder eine neue Major-Version, wenn der Bruch bleibt, und die betroffene Version zu dokumentieren, damit Nutzer wissen, dass sie sie überspringen sollten.

Brauchen rein interne Änderungen einen Versionssprung? Nein. Semantic Versioning verfolgt die öffentliche Schnittstelle. Ein Refactoring ohne beobachtbare Wirkung für eine Aufruferin braucht weder Sprung noch Changelog-Eintrag, selbst wenn es intern erhebliche Arbeit war.

Die technischen Aussagen in diesem Artikel wurden nicht unabhängig geprüft. Wenn etwas nicht stimmt, sagen Sie es uns, und wir korrigieren es.

Mehr bei changeloop: Changelog-Generator, Entwicklerdokumentation