Keep a Changelog, tatsächlich umgesetzt
5 Min. Lesezeit aktualisiert am
Keep a Changelog ist eine einseitige Konvention für eine CHANGELOG.md: neueste Version zuerst,
ein Abschnitt pro Version mit Nummer und ISO-Datum, Einträge gruppiert unter sechs Typen (Added,
Changed, Deprecated, Removed, Fixed, Security), und ein Unreleased-Abschnitt oben für Einträge
zwischen Releases. Die meisten Teams, die sich darauf berufen, setzen etwa zwei Drittel davon um,
und das Drittel, das sie weglassen, ist das Drittel, das ihre Nutzer schützt.
Olivier Lacan veröffentlichte Keep a Changelog 2014 mit einem Satz, der besser gealtert ist als die meiste Software-Prosa: don’t let your friends dump git logs into changelogs. Zehn Jahre später ist es das Nächste, was dieser Teil der Software zu einem Standard hat. Es lohnt sich, die Quelle statt einer Zusammenfassung zu lesen; hier geht es um die Teile, die wegfallen.
Was verlangt Keep a Changelog?
Eine CHANGELOG.md im Repo-Root, neueste zuerst, mit einem Abschnitt pro Version. Jede Version
trägt eine Nummer und ein ISO-Datum und gruppiert ihre Einträge unter sechs Typen:
| Typ | Wofür | Was das Weglassen kostet |
|---|---|---|
| Added | Neue Features | Nichts; das lässt niemand weg |
| Changed | Änderungen an bestehendem Verhalten | Leserinnen entdecken eine Verhaltensänderung erst durch einen Fehler |
| Deprecated | Features, die entfernt werden | Eine Entfernung wird zum Vorfall statt zum geplanten Ereignis |
| Removed | In diesem Release entfernte Features | Niemand unterscheidet eine Entfernung von einem Bug |
| Fixed | Bugfixes | Nichts; auch das lässt niemand weg |
| Security | Sicherheitslücken | Die eine Person, die danach sucht, findet nichts |
Plus ein Unreleased-Abschnitt oben, damit ein Eintrag sofort nach dem Merge einen Platz hat und
jeder sehen kann, was kommt.
Das ist fast alles. Der Rest ist die Begründung: Einträge sind für Menschen, ein Eintrag pro Änderung, und die Datei ist ein Dokument, kein Log.
Welche Teile von Keep a Changelog fallen weg?
Der Unreleased-Abschnitt, dann vier der sechs Typen, Security unter ihnen, in dieser Reihenfolge.
Unreleased verschwindet zuerst. Es ist der Abschnitt ohne Frist, also der, dessen Pflege
zuerst aufhört, und sobald er weg ist, werden Einträge zum Releasezeitpunkt aus der Commit-Historie
geschrieben. Genau das ist der Git-Log-Dump, vor dem die Spezifikation gleich zu Beginn warnt, nur
schrittweise erreicht. Changelog-Automatisierung handelt größtenteils
davon, diesen Abschnitt am Leben zu halten, ohne dass sich jemand daran erinnern muss.
Die sechs Typen kollabieren zu zwei. Die meisten echten Changelogs landen bei Added und Fixed, weil Changed und Deprecated ein Urteil verlangen, worauf sich jemand verlassen hat. Genau dieses Urteil ist der wertvolle Teil. Deprecated ist besonders der einzige Typ, der ein Versprechen über die Zukunft ist, und ihn wegzulassen ist, wie aus einer Entfernung ein Vorfall wird; die Mechanik, dieses Versprechen zu halten, steht in Wie man eine API abkündigt.
Security hört auf, separat zu sein. Ein Sicherheitsfix unter Fixed ist für die eine Person unsichtbar, die genau danach gesucht hat. Halte ihn getrennt, auch wenn der Fix trivial ist, und besonders dann, wenn du lieber keine Aufmerksamkeit darauf ziehen würdest.
Was beantwortet die Spezifikation nicht?
Es ist ein Dateiformat. Es sagt nichts zu den Fragen, auf die man unmittelbar nach der Einführung stößt:
- Wie erfährt es jemand? Eine Datei im Repo erreicht Mitwirkende. Sie erreicht nicht eine Kundin, die nie GitHub geöffnet hat.
- Was ist mit Produkten ohne Versionen? Ein kontinuierlich deployter Dienst hat keine v4.2.0, nach der man gruppieren könnte. Die meisten Teams setzen stattdessen Daten ein, was funktioniert, und die Spezifikation befürwortet oder verbietet das nicht.
- Wer schreibt den Eintrag? Die Spezifikation geht davon aus, dass ein Mensch es tut. Sie sagt nicht, wann.
- Was ist mit mehreren Zielgruppen? Eine Datei bedient Entwickler. Sie liefert nicht denselben Inhalt an eine nicht-technische Administratorin, und ihn für sie von Hand umzuformatieren ist, wo die Duplizierung anfängt. Changelog vs. Release Notes ist die Trennung, die die Spezifikation einem selbst überlässt.
Common Changelog, ein strengerer Fork der Idee, zieht einiges davon an: Es verbietet bestimmte Formulierungen, verlangt einen Link zur Änderung und hat eine klare Meinung dazu, wer die Leserin ist. Lesenswert, wenn die losen Stellen von Keep a Changelog das sind, worüber euer Team immer wieder streitet.
Kann man Keep a Changelog automatisieren, ohne Git-Logs abzukippen?
Ja: Leite den Entwurf aus strukturierten Commits ab, setze ihn mit vorausgefülltem Typ in Unreleased, und verlange, dass ein Mensch die Formulierung bearbeitet, bevor ein Release geschnitten wird. Die Warnung der Spezifikation gilt der Ausgabe, nicht dem Werkzeug. Einen Entwurf aus Commits abzuleiten ist in Ordnung. Diesen Entwurf unbearbeitet zu veröffentlichen ist das, wogegen sie sich richtet.
Die Maschine übernimmt Sammeln und Formatieren, das kann sie gut. Der Mensch übernimmt Auswahl und Formulierung, das kann sie nicht. Conventional Commits behandelt die zweischichtige Aufteilung, auf der das beruht, und welche Commit-Typen auf welche der sechs Kategorien oben abbilden. Unsere Übersicht Changelog-Tools deckt ab, was es für die Sammel-Hälfte gibt.
Wo hört Keep a Changelog auf, genug zu sein?
Bei der Distribution. Keep a Changelog ist eine gute Antwort auf “wie sollte diese Datei aussehen”. Es ist keine Antwort auf “wie erfahren unsere Nutzer, was sich geändert hat”, denn eine Markdown-Datei im Repo ist eine Distributionsstrategie, die nur funktioniert, wenn die Nutzer Mitwirkende sind.
Das ist die Lücke, auf die die meisten Teams als Zweites stoßen: Die Datei ist in Ordnung, und niemand außerhalb des Teams liest sie. Sie zu schließen bedeutet, dass die Einträge zu Daten werden müssen, die sich woanders rendern lassen, was ein anderes Problem ist als das Formatieren einer Datei, und der Grund, warum Changelog-Beispiele öffentliche Changelog-Seiten sammelt statt Repo-Dateien. Wie man aus diesen Einträgen etwas macht, zu dem Leute zurückkehren, behandelt eine Changelog-Seite bauen.
Führt die Spezifikation trotzdem ein. Es kostet einen Nachmittag, es macht das zweite Problem angehbar, und es ist immer noch die beste Seite, die je darüber geschrieben wurde.
FAQ
Ist Keep a Changelog ein Standard? Es ist eine weit verbreitete Konvention, keine Spezifikation eines Standardisierungsgremiums. Werkzeuge (Release-Skripte, Linter, Parser) gehen oft genug von dieser Form aus, dass sie zu befolgen Kompatibilität einbringt.
Was kommt in den Unreleased-Abschnitt? Jeder Eintrag für eine Änderung, die gemergt, aber noch nicht in einem nummerierten Release ausgeliefert wurde. Wird ein Release geschnitten, wird der Abschnitt in Version und Datum umbenannt, und ein frischer, leerer Unreleased-Abschnitt kommt darüber.
Sollte ein Changelog semantische Versionierung nutzen? Keep a Changelog empfiehlt es und verlangt es nicht. Bibliotheken und APIs profitieren davon; ein kontinuierlich deployter Dienst setzt meist stattdessen Daten ein, was das Format zulässt.
Sollten Security-Fixes im Changelog stehen, bevor sie öffentlich sind? Füge den Eintrag hinzu, wenn der Fix ausgeliefert wird, mit genug Detail, damit eine Betreiberin handeln kann, und nicht mehr. Den Eintrag bis zu einem koordinierten Offenlegungsdatum zu verzögern ist normal; ihn wegzulassen nicht.
Die technischen Aussagen in diesem Artikel wurden nicht unabhängig geprüft. Wenn etwas nicht stimmt, sagen Sie es uns, und wir korrigieren es.