Changelog-Dateiformate: JSON, YAML oder einfach Markdown
5 Min. Lesezeit
Die meisten Teams starten einen Changelog als Markdown-Datei, weil es der Weg des geringsten Widerstands ist: lesbar im Diff eines Pull Requests, lesbar auf GitHub ohne irgendetwas zu rendern, und vertraut für jeden, der je eine README geschrieben hat. Diese Wahl funktioniert einwandfrei, bis etwas anderes als ein Mensch die Datei lesen muss, eine Seite, ein Widget, eine E-Mail-Zusammenfassung, und dann hört das Format auf, kostenlos zu sein. Changelog-Automatisierung behandelt die strukturelle Anforderung allgemein, ein Typ, ein Datum, ein Text und ein Link; hier geht es darum, welches Dateiformat diese Struktur tatsächlich liefert und was es jeweils kostet, dorthin zu kommen.
Was ist falsch an einem einfachen Markdown-Changelog?
Nichts, bis etwas die Datei zurück in Felder parsen muss. Eine Überschrift, ein Datum und eine Liste darunter ist für eine Person trivial zu lesen und wirklich schwer, zuverlässig zu parsen, weil Markdown kein Schema hat: Das Datum könnte in der Überschrift stehen, in fettem Text auf der ersten Zeile, oder bei einem alten Eintrag ganz fehlen, und jede dieser Varianten ist gültiges Markdown, das ein Mensch korrekt liest und ein Parser nicht. Teams, die einen Markdown-Changelog automatisieren, landen meist bei einem selbstgebauten Regex-Parser, der beim ersten leichten Abdriften der Formatierung eines Eintrags bricht, was oft passiert, weil beim Schreiben nichts Konsistenz erzwingt.
Was bringt ein strukturiertes Format tatsächlich?
Eine Garantie, dass jeder Eintrag dieselbe Form hat, geprüft beim Schreiben des Eintrags statt erraten beim Lesen. Eine JSON- oder YAML-Datei mit definiertem Schema, Typ, Datum, Version, Zielgruppe, Text, Link, schlägt laut fehl, wenn ein Pflichtfeld fehlt, genau wie es eine strikte API-Antwort täte; eine Markdown-Datei rendert einfach, was da ist, korrekt oder nicht. Dieser Unterschied ist unsichtbar, bis der Tag kommt, an dem ein Skript das Datum jedes Eintrags braucht, um einen Feed zu sortieren, und die Hälfte der Einträge hat es an einer anderen Stelle.
# CHANGELOG.yml
- date: 2026-09-05
type: breaking
version: v2
audience: api
body: "POST /invoices now rejects a currency mismatch instead of silently converting."
link: /blog/api-changelog/Heißt das, die menschenlesbare Datei muss verschwinden?
Nein, und der Versuch, eine YAML- oder JSON-Datei gleichzeitig als das lesen zu lassen, was eine Person in einem Pull Request liest, ist meist ein Fehler in die andere Richtung: einen Diff aus verschachteltem JSON zu reviewen ist schlimmer als einen Satz Prosa zu reviewen, und eine Reviewerin, die eine Datenstruktur gedanklich parsen muss, um einen Formulierungsfehler zu fangen, ist eine Reviewerin, die irgendwann aufhört, Formulierungsfehler zu fangen. Die beiden Formate können koexistieren: strukturierte Daten sind die Quelle der Wahrheit, die eine Automatisierungs-Pipeline liest, und ein generiertes Markdown- oder HTML-Rendering ist, was eine Person tatsächlich reviewt und liest, erzeugt aus der strukturierten Datei, statt von Hand daneben gepflegt zu werden.
| Format | Menschenlesbar so wie es ist | Maschinell parsbar ohne eigenen Code | Häufiger Fehlermodus |
|---|---|---|---|
| Markdown | Ja | Nein | Inkonsistente Eintragsform bricht naive Parser |
| JSON | Schlecht | Ja | Umständlich; leicht von Hand in ungültiges JSON zu editieren |
| YAML | Mittel | Ja | Whitespace-sensitiv; eine falsche Einrückung ist ein stiller, kein lauter Parse-Fehler |
Welches strukturierte Format ist tatsächlich leichter von Hand zu editieren, JSON oder YAML?
YAML, für jeden, der Einträge von Hand schreibt statt über einen Generator, weil es das Quoting und Klammer-Matching wegfallen lässt, das JSON für jeden String und jedes verschachtelte Objekt verlangt. Der Nachteil ist, dass YAMLs Whitespace-Sensitivität auf eine Art still fehlschlägt, wie JSONs Klammer-Mismatches es meist nicht tun: Ein JSON-Parser lehnt fehlerhaften Input rundweg ab, während ein YAML-Parser eine schlecht eingerückte Datei akzeptieren und einfach in die falsche Struktur parsen kann, was ein schlimmerer Fehler ist, weil nichts euch sagt, dass es passiert ist. Wenn Einträge nur je von einem Skript geschrieben werden, verschwindet dieser Nachteil meist, und JSONs strikteres Parsing wird zur sichereren Standardwahl.
Braucht eine Changelog-Seite ein eigenes strukturiertes Format, getrennt von der Datei, die sie speist?
Kein separates, dasselbe, nur anders gerendert. Eine Changelog-Seite behandelt, wie man die Seite selbst über einen JSON-Feed und schema.org-Markup maschinenlesbar macht; dieser Feed ist generierter Output, keine zweite Quelle der Wahrheit, die synchron zur zugrunde liegenden Datei gehalten werden muss. Strukturierte Daten von Hand an zwei Stellen zu pflegen, einer Quelldatei und dem Feed einer Seite, ist, wie die beiden auseinanderdriften, also sollte die hier getroffene Entscheidung zum Dateiformat das eine sein, aus dem alles nachgelagerte, Seite, Widget, E-Mail, generiert wird, nie von Hand kopiert.
Lohnt sich der Migrationsaufwand, einen bestehenden Markdown-Changelog auf ein strukturiertes Format umzustellen?
Meist erst, wenn Automatisierung das eigentliche Ziel ist, nicht vorher. Ein Ein-Personen-Projekt, das eine Markdown-Datei in eine GitHub-README veröffentlicht, hat keinen echten Automatisierungsbedarf, und sie auf YAML umzustellen bringt nichts außer Zeremonie. Die Konvertierung zahlt sich aus in dem Moment, in dem mehr als ein nachgelagerter Konsument, eine Seite, eine Digest-E-Mail, ein öffentlicher Feed, dieselben Daten lesen muss, weil genau das der Punkt ist, an dem die Inkonsistenzen eines Markdown-Parsers anfangen, sichtbar falschen Output zu produzieren, statt nur lästig zu pflegen zu sein.
FAQ
Kann ein Markdown-Changelog parsbar gemacht werden, ohne komplett das Format zu wechseln? Teilweise, mit Frontmatter: ein kleiner YAML-Block am Anfang jedes Eintrags (Datum, Typ, Version) neben einem Markdown-Text für die Prosa. Das liefert die strukturierten Felder, die ein Parser braucht, ohne den ganzen Eintrag in JSON oder YAML zu zwingen, und ist ein vernünftiger Mittelweg für ein Team, das noch nicht für eine volle Migration bereit ist.
Spielt das Dateiformat eine Rolle für SEO oder dafür, wie eine Changelog-Seite rankt? Nicht direkt. Suchmaschinen lesen die gerenderte Seite, nicht die Quelldatei, also ist das Dateiformat für sie unsichtbar; was für die Seite selbst zählt, ist, ob sie aus eigenem Recht maschinenlesbar ist, was ein separates Anliegen davon ist, was sie erzeugt.
Sollte jeder Changelog-Eintrag durch dieselbe Datei laufen, oder können Typen auf Dateien aufgeteilt werden? Eine Datei ist einfacher, bis das Eintragsvolumen sie unhandlich macht zu diffen oder zu reviewen; nach Jahr oder Kategorie aufzuteilen ist ein vernünftiges Ventil, sobald die Diffs einer einzelnen Datei zu groß werden, um sie sinnvoll zu reviewen, aber es fügt einen Merge-Schritt hinzu, bevor irgendetwas nachgelagert „alle Einträge” als eine Liste lesen kann.
Gibt es ein Standard-Changelog-Dateiformat, so wie es einen Standard für RSS gibt? Kein breit übernommenes. Keep a Changelog schlägt eine Markdown-Konvention vor, und mehrere Tools haben ihr eigenes; ein Changeset ist eine Markdown-Datei mit YAML-Frontmatter, die das Paket und den Versionssprung nennt, also genau das oben beschriebene Frontmatter-Muster. Keins davon ist ein Format, das andere Tools out of the box lesen, so wie RSS-Reader universell RSS verstehen.
Die technischen Aussagen in diesem Artikel wurden nicht unabhängig geprüft. Wenn etwas nicht stimmt, sagen Sie es uns, und wir korrigieren es.