Software verändert sich ständig. Abhängigkeiten werden aktualisiert, Fehler korrigiert, Funktionen ergänzt und Schnittstellen entfernt. Git speichert diese Arbeit präzise. Trotzdem beantwortet ein Commit-Verlauf nur selten die wichtigste Frage der Nutzer: Was hat sich für mich geändert?
Keep a Changelog und Semantic Versioning lösen zwei unterschiedliche Teile dieses Problems. Der Changelog beschreibt relevante Veränderungen in menschlicher Sprache. Semantic Versioning kennzeichnet, welche Tragweite eine Veröffentlichung hat.
Für KI ist beides wertvoll, weil der aktuelle Zustand allein nicht erklärt, wie er entstanden ist und welche Übergänge berücksichtigt werden müssen.
Keep a Changelog: kuratierte Veränderung statt Commit-Ablage
Ein Changelog ist eine chronologisch geordnete Liste bemerkenswerter Änderungen pro Version. Keep a Changelog empfiehlt unter anderem:
- eine Sektion für noch nicht veröffentlichte Änderungen,
- neueste Versionen zuerst,
- Veröffentlichungsdatum pro Version,
- verlinkbare Versionen und Abschnitte,
- Gruppierung nach Art der Änderung.
Übliche Kategorien sind:
Addedfür neue Funktionen,Changedfür verändertes Verhalten,Deprecatedfür angekündigte Ablösungen,Removedfür entfernte Funktionen,Fixedfür Fehlerkorrekturen,Securityfür sicherheitsrelevante Änderungen.
Der entscheidende Unterschied zum Git-Log ist die Auswahl. Ein Changelog enthält, was Nutzer, Betreiber und Integratoren wissen müssen. Merge-Commits, interne Umbenennungen und jede korrigierte Einrückung gehören nicht automatisch hinein.
Semantic Versioning: eine Sprache für Kompatibilität
Semantic Versioning verwendet das Schema MAJOR.MINOR.PATCH, beispielsweise 3.4.2.
- MAJOR steigt bei inkompatiblen Änderungen an der öffentlichen Schnittstelle.
- MINOR steigt bei rückwärtskompatiblen neuen Funktionen.
- PATCH steigt bei rückwärtskompatiblen Fehlerkorrekturen.
Diese Bedeutung funktioniert nur, wenn die öffentliche Schnittstelle definiert ist. Bei einer Bibliothek sind das etwa exportierte Funktionen und Datentypen. Bei einem Dienst können API, Konfiguration, Datenformate oder Betriebsverhalten dazugehören.
Ohne diese Grenze wird SemVer zur dekorativen Zahlenfolge. Dann bedeutet 2.0.0 vielleicht „neues Logo“, „großer Umbau“ oder „Marketing fand die Eins hübsch“.
Warum KI beide Informationen braucht
Ein Agent sieht im aktuellen Code, welche Funktion heute existiert. Für Migration, Fehleranalyse und Aktualisierung muss er zusätzlich wissen:
- Seit welcher Version gilt das Verhalten?
- Wurde eine Schnittstelle absichtlich entfernt?
- Welche Übergangsfrist bestand?
- Ist eine Konfiguration weiterhin kompatibel?
- Welche Sicherheitskorrektur verlangt ein Update?
- Welche ältere Anleitung bezieht sich auf einen historischen Stand?
Der Changelog erklärt die fachliche Veränderung. Die Versionsnummer ordnet ihre Kompatibilitätswirkung ein. Gemeinsam verhindern sie, dass eine KI aktuelle Lösungen auf falsche Versionen überträgt.
Ein brauchbares Beispiel
# Changelog
## [Unreleased]
### Added
- Export von Suchergebnissen als CSV.
## [2.0.0] - 2026-07-31
### Changed
- Authentifizierung verwendet jetzt OAuth 2.1 statt API-Schlüssel.
### Removed
- Veralteten Endpunkt `/v1/login` entfernt.
### Security
- Sitzungen werden nach Passwortänderungen vollständig widerrufen.
Hier wird deutlich, dass Version 2.0.0 eine inkompatible Änderung enthält. Ein Agent kann bei einer Migration gezielt nach der alten Anmeldung suchen und betroffene Dokumentation markieren.
Was in einen guten Eintrag gehört
Eine Changelog-Zeile sollte möglichst drei Dinge erklären:
- Was hat sich verändert?
- Wen oder was betrifft es?
- Ist eine Handlung erforderlich?
Statt „Auth refactored“ ist hilfreicher:
API-Schlüssel durch OAuth 2.1 ersetzt. Bestehende Integrationen müssen vor dem Update neue Zugangsdaten verwenden.
Der zweite Satz macht aus Aktivität eine relevante Information.
KI kann den Changelog vorbereiten, aber nicht kuratieren
Aus Commits, Pull Requests und Tickets kann KI einen guten Entwurf erstellen. Sie kann Änderungen gruppieren, technische Formulierungen vereinfachen und fehlende Migrationshinweise markieren.
Die Freigabe braucht weiterhin Menschen, die beurteilen können:
- welche Änderung für Nutzer bemerkenswert ist,
- ob die Versionsnummer zur tatsächlichen Wirkung passt,
- ob sicherheitsrelevante Details veröffentlicht werden dürfen,
- ob ein Breaking Change ausreichend vorbereitet wurde,
- ob Dokumentation und Betrieb denselben Stand beschreiben.
Ein automatisch erzeugter Changelog, der nur Commit-Titel umformuliert, ist ein Git-Log mit besserem Benehmen.
Changelog, ADR und Dokumentation zusammendenken
Die drei Formen beantworten verschiedene Fragen:
- ADR: Warum wurde eine bedeutsame Entscheidung getroffen?
- Dokumentation: Wie funktioniert der aktuelle Stand?
- Changelog: Was hat sich zwischen Ständen verändert?
Ein Release kann auf das ADR verweisen, das den Umbau begründet. Die aktuelle Referenz beschreibt die neue Schnittstelle. Der Changelog erklärt Migration und Auswirkungen. Keine Quelle muss die anderen kopieren.
Ein pragmatischer Release-Ablauf
- Relevante Änderungen während der Entwicklung unter
Unreleasedsammeln. - Vor dem Release Einträge fachlich und sprachlich kuratieren.
- Kompatibilitätswirkung bestimmen.
- Passende Versionsnummer vergeben.
- Veröffentlichungsdatum und Links ergänzen.
- Migration, Dokumentation und Sicherheitsfolgen prüfen.
- Version taggen und den veröffentlichten Stand unverändert bewahren.
So entsteht eine nachvollziehbare Kette zwischen Entscheidung, Umsetzung und Betrieb.
Fazit
Keep a Changelog erklärt Veränderungen für Menschen. Semantic Versioning ordnet ihre Kompatibilitätswirkung ein. Beides reduziert Unsicherheit bei Updates, Migrationen und Fehleranalysen.
Auch KI profitiert davon. Sie muss nicht aus Codeunterschieden erraten, welche Änderung relevant oder absichtlich war. Sie erhält einen kuratierten Verlauf – und damit die zeitliche Dimension, die einem reinen Wissensstand fehlt.
