Changelog vs. Release Notes: Was ist der Unterschied?

Ein Changelog ist eine laufende, kumulative Aufzeichnung von allem, was sich geändert hat, geschrieben für jemanden, der etwas nachschlägt. Release Notes sind eine kuratierte Botschaft zu einem Release, geschrieben für jemanden, der entscheidet, ob es ihn betrifft. Der Unterschied liegt im Publikum, nicht in der Formatierung, und die meisten Teams brauchen beides: eins als Referenz, eins als Ankündigung, abgeleitet aus denselben Einträgen.

Die meisten Teams landen bei einem davon aus Zufall und beim anderen auf Nachfrage. Man startet mit einem Changelog, weil ein Entwickler eine Aufzeichnung dessen will, was ausgeliefert wurde. Monate später fragt jemand im Support, warum Kunden nichts von einem Feature wussten, das seit April live ist, und plötzlich braucht man Release Notes.

Changelog vs. Release Notes im Vergleich

Was ist ein Changelog?

Ein Changelog ist eine chronologische, nahezu vollständige Aufzeichnung dessen, was sich geändert hat, neueste zuerst, mit jedem Eintrag typisiert (added, changed, deprecated, removed, fixed, security) und datiert. Seine Leserin hat sich schon entschieden, dass es sie interessiert. Sie schlägt etwas nach: wann sich ein Verhalten geändert hat, ob ein Bug behoben ist, welche Version ein Flag eingeführt hat. Vollständigkeit ist der ganze Wert, weshalb die Konvention Keep a Changelog den Großteil ihrer einen Seite auf Struktur verwendet und fast nichts auf Prosa.

Was sind Release Notes?

Release Notes sind eine selektive, in Prosa geschriebene Botschaft zu einem Release. Ihre Leserin hat noch nichts entschieden. Sie entscheidet, ob dieses Release für sie zählt und ob sie deswegen etwas tun muss. Auswahl ist der ganze Wert: Eine Release Note, die alles auflistet, ist ein Changelog mit Absätzen, und sie enttäuscht die Leserin genauso, wie ein Changelog, der Dinge weglässt, seine Leserin enttäuscht. Wie man Release Notes schreibt handelt von der Auswahl und der Formulierung.

Braucht man Changelog und Release Notes zusammen?

Man braucht beides, sobald die beiden Zielgruppen unterschiedliche Dinge wollen; bis dahin ist ein Format, das beide Aufgaben übernimmt, richtig. Kleine Teams veröffentlichen eine einzige /changelog-Seite mit einem kurzen Absatz oben in jedem Eintrag, und eine Weile dient das einem Entwickler, der einen Fix sucht, und einer Kundin, die nach Neuigkeiten stöbert, gleichermaßen. Zu früh zu trennen gibt einem zwei Dinge zu pflegen, und eines davon verrottet.

Die Trennung lohnt sich, sobald Folgendes passiert:

• Eure Changelog-Einträge haben erklärende Absätze bekommen, an denen Entwickler vorbeiscrollen.
• Oder das Gegenteil: Eure Release-Ankündigungen haben angefangen, Abhängigkeits-Updates aufzulisten.
• Der Support kopiert Einträge in E-Mails und schreibt sie dabei um.
• Jemand fragt nach “nur den Breaking Changes”, und ihr könnt nicht danach filtern.

Das Letzte ist das echte Signal. Wenn niemand “was hat sich geändert, das mich betrifft” beantworten kann, ohne alles zu lesen, habt ihr ein Format, das zwei Jobs schlecht macht.

Eine Quelle, zwei Ansichten

Der Fehler ist, sie als zwei Dokumente zu behandeln. Es sind zwei Ansichten über dieselbe Menge Änderungen.

Schreibe den Changelog laufend, ein Eintrag pro bedeutsamer Änderung, jeder getaggt mit dem, was er ist: fixed, added, changed, removed, deprecated, security. Halte die Einträge kurz genug, dass das Schreiben eines Eintrags keine Entscheidung ist. Zum Releasezeitpunkt sind Release Notes dann eine Auswahl und eine Umformulierung: Nimm die Einträge, die für einen Menschen zählen, gruppiere sie danach, was sie jemanden tun lassen, und stelle den Grund nach oben.

Das hat eine praktische Konsequenz. Wenn der Changelog die Quelle ist, muss er strukturierte Daten sein, keine handgepflegte Seite. Ein Eintrag braucht einen Typ, ein Datum, eine Version und eine Art zu sagen, für wen er ist. Sobald das steht, sind die öffentliche Seite, das In-App-Widget und der RSS- oder JSON-Feed drei Darstellungen einer Sache, und niemand schreibt auf dem Weg zur Kundin noch etwas um. Eine Release-Notes-E-Mail kann denselben Eintrag zitieren, aus welchem Tool auch immer eure E-Mails verschickt werden. Changelog-Automatisierung handelt davon, welchen dieser Schritte eine Maschine übernehmen sollte. Das ist das ganze Argument dafür, einen Changelog als Feed statt als Seite zu behandeln. Es ist auch, ganz offen, was wir bauen, also lies das als Interesse, nicht als neutrale Umfrage.

Wenn du nur für eines Zeit hast

Schreibe den Changelog. Er ist günstiger pro Eintrag, nützlich am Tag, an dem du ihn schreibst, und Release Notes lassen sich später daraus ableiten. Umgekehrt geht es nicht: Man kann ein Jahr voller Änderungen nicht aus zwölf Ankündigungs-E-Mails rekonstruieren, und man wird danach gefragt werden.

Halte ihn in einem festen Format, damit die Ableitung möglich bleibt. Unsere Seite Changelog-Beispiele sammelt Einträge von Teams, die das gut machen, und die Release-Notes-Vorlage ist die Form, die wir nutzen, wenn wir aus einer Reihe von Einträgen etwas Sendenswertes machen.

Eine Anmerkung zur Benennung

Nichts davon ist standardisiert, und man findet “Release Notes” für eine laufende Liste und “Changelog” für eine vierteljährliche Ankündigung. Über die Worte zu streiten lohnt sich nicht. Entscheide, welche der beiden Aufgaben jedes eurer Formate erfüllt, nenne es, wie euer Team es schon nennt, und stelle sicher, dass keines still beide macht.

Auf welcher Oberfläche das Ergebnis landet, ist eine eigene Entscheidung, behandelt in eine Changelog-Seite bauen.

FAQ

Ist ein Changelog dasselbe wie Release Notes? Nein. Ein Changelog ist die vollständige Aufzeichnung, gelesen von Leuten, die etwas nachschlagen; Release Notes sind die ausgewählte Ankündigung, gelesen von Leuten, die entscheiden, ob es sie interessiert. Dieselbe Änderung erscheint in beiden, für jede Leserin anders formuliert.

Können Release Notes aus einem Changelog erzeugt werden? Ja, und das ist die richtige Richtung. Wähle die Einträge aus, die einen Menschen interessieren würden, gruppiere sie nach Ergebnis, formuliere die Überschrift neu. Umgekehrt, einen Changelog aus Ankündigungen zu rekonstruieren, verliert alles, was die Ankündigungen weggelassen haben.

Wo sollte ein Changelog leben? An einem dauerhaften, verlinkbaren Ort, den die Leserin ohne Repository erreicht: eine /changelog-Seite, eine Doku-Seite, oder ein Feed, der sich an mehreren Orten rendert. Eine CHANGELOG.md allein erreicht Mitwirkende, keine Kunden.

Sollte ein Changelog interne Änderungen enthalten? Ja, ganz unten, je eine Zeile. Der Changelog ist die vollständige Aufzeichnung. Release Notes können sie auch aufführen, in einem kurzen letzten Abschnitt, solange die Änderungen, die eine Leserin bemerkt, zuerst kommen.

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-Beispiele, Vorlage für Release Notes