guides

Ein Changelog ist eine Datei, die die bemerkenswerten Änderungen an einem Projekt auflistet, nach Version geordnet. Ihre Aufgabe ist es, für alle, die Ihre Software nutzen oder von ihr abhängen, eine einfache Frage zu beantworten: Was hat sich zwischen der Version, die ich hatte, und der Version, auf die ich umsteige, geändert. Weil es für Menschen und nicht für Maschinen geschrieben ist, hebt ein gutes Changelog hervor, was für die Nutzer wirklich zählt, und lässt das Rauschen weg.

Es hilft, klarzustellen, was ein Changelog nicht ist. Es ist nicht die rohe Ausgabe Ihrer Versionsverwaltung. Ein git log listet jeden Commit auf, auch winzige Refactorings, Tippfehlerkorrekturen und Merge-Commits, in der Reihenfolge, in der sie gemacht wurden, und in der Formulierung, die der Autor gerade gewählt hat. Ein Changelog ist eine kuratierte, von einem Menschen geschriebene Zusammenfassung, die zusammengehörige Arbeit gruppiert, triviale Details weglässt und jede Änderung anhand ihrer Wirkung auf den Lesenden beschreibt.

Die am weitesten verbreitete Konvention, um eines zu schreiben, heißt Keep a Changelog. Sie legt ein schlichtes, auf Markdown basierendes Format fest, meist in einer Datei namens CHANGELOG.md im Wurzelverzeichnis des Repositorys. Der Gedanke ist, dass eine einheitliche, vorhersehbare Struktur die Datei leicht überfliegbar macht, ob der Leser nun eine Person ist, die auf einem Code-Host stöbert, oder ein Werkzeug, das die Einträge auswertet.

Das Keep-a-Changelog-Format

Nach dieser Konvention erhält jede veröffentlichte Version einen eigenen Abschnitt, überschrieben mit der Versionsnummer und dem Veröffentlichungsdatum. Innerhalb einer Version werden Änderungen unter einer kleinen Menge von Standardüberschriften gruppiert, damit die Lesenden schnell finden, was ihnen wichtig ist. Die empfohlenen Gruppen sind Added für neue Funktionen, Changed für Änderungen an bestehendem Verhalten, Deprecated für Funktionen, die auslaufen, Removed für inzwischen entfernte Funktionen, Fixed für Fehlerbehebungen und Security für alles, was Schwachstellen betrifft.

Die Versionen selbst folgen meist der Semantischen Versionierung, sodass eine Version als MAJOR.MINOR.PATCH gelesen wird, etwa 2.4.1. Das verknüpft das Changelog auf nützliche Weise mit der Versionsnummer: Ein Leser kann den Sprung von einer Version zur nächsten betrachten und sich eine Erwartung bilden. Eine Änderung der Hauptnummer signalisiert, dass etwas brechen könnte, während eine Erhöhung der Patch-Nummer nur Korrekturen nahelegt. Das Changelog erklärt dann in Worten, was genau hinter dieser Nummer steckt.

Reihenfolge, Daten und der Unreleased-Abschnitt

Ein Changelog wird üblicherweise in umgekehrter chronologischer Reihenfolge geführt, mit der neuesten Version oben, damit die relevanteste Information das Erste ist, was ein Leser sieht. Jeder Eintrag ist datiert, was es erlaubt, eine Veröffentlichung zeitlich einzuordnen und zu verstehen, wie aktuell eine Korrektur oder Funktion ist. Reihenfolge und Datumsangaben einheitlich zu halten, gehört zu dem, was die Datei auf einen Blick vertrauenswürdig macht.

• Ein Changelog ist eine Datei, die die bemerkenswerten Änderungen jeder Version auflistet, für Menschen geschrieben, nicht das rohe git log.
• Keep a Changelog ist die gängige Konvention, meist eine CHANGELOG.md in Markdown im Wurzelverzeichnis des Repositorys.
• Standard-Änderungsgruppen: Added, Changed, Deprecated, Removed, Fixed und Security.
• Versionen folgen meist der Semantischen Versionierung (MAJOR.MINOR.PATCH), jede mit ihrem Veröffentlichungsdatum.
• Einträge stehen in umgekehrter chronologischer Reihenfolge, oft mit einem Unreleased-Abschnitt oben.
• Einträge lassen sich aus Commits erzeugen (etwa Conventional Commits), doch ein von Hand geschriebenes Changelog ist oft klarer.

Eine gängige und praktische Ergänzung ist ein Unreleased-Abschnitt ganz oben. Dort halten Sie Änderungen fest, während Sie sie vornehmen, bevor sie an eine Versionsnummer gebunden sind. Wenn Sie zur Veröffentlichung bereit sind, benennen Sie diesen Abschnitt in die neue Version um, geben ihm ein Datum und beginnen einen frischen Unreleased-Block. Diese Gewohnheit sorgt dafür, dass das Changelog geschrieben wird, solange die Arbeit frisch ist, statt in letzter Minute aus dem Gedächtnis rekonstruiert zu werden.

Gute Einträge schreiben und erzeugen

Gute Einträge zu schreiben heißt vor allem, den Leser im Blick zu behalten. Jede bemerkenswerte Änderung sollte einen eigenen Eintrag bekommen, so formuliert, dass auch jemand, der die Interna nicht kennt, die Wirkung versteht. Es lohnt sich, das Ergebnis für den Nutzer zu beschreiben statt der Mechanik des Codes, internen Fachjargon zu vermeiden und zusammengehörige Änderungen in einer einzigen klaren Zeile zu bündeln statt eines Eintrags pro Commit. Triviale oder rein interne Änderungen können ganz weggelassen werden.

Es ist möglich, ein Changelog automatisch aus Ihrer Commit-Historie zu erzeugen, und viele Teams tun das. Ansätze wie Conventional Commits verlangen, Commit-Nachrichten strukturiert zu schreiben, etwa mit dem Präfix feat oder fix, damit ein Werkzeug sie in die richtigen Gruppen einsortieren und einen Entwurf zusammenstellen kann. Das kann Zeit sparen und für Einheitlichkeit sorgen, doch das Ergebnis liest sich oft wie eine Liste von Commits. Ein von Hand geschriebenes oder zumindest überarbeitetes Changelog ist häufig klarer, weil ein Mensch entscheiden kann, was erwähnenswert ist, und es für das Publikum formulieren kann.

Zusammenfassung

Kurz gesagt ist ein Changelog eine gut lesbare Aufzeichnung dessen, was sich in jeder Version eines Projekts geändert hat, geführt für die Menschen, die es nutzen. Die Konvention Keep a Changelog gibt ihm eine vorhersehbare Gestalt, die Semantische Versionierung verleiht seinen Versionsnummern Bedeutung, und ein wenig Disziplin, etwa ein Unreleased-Abschnitt und ein Eintrag pro bemerkenswerter Änderung, hält es korrekt. Ob von Hand geschrieben oder aus Commits erzeugt, sein Wert entsteht daraus, klar, aktuell und auf das ausgerichtet zu sein, was der Leser wirklich wissen muss.