Git-Tags, Releases und dein Changelog

Ein Git-Tag, ein Release und ein Changelog-Eintrag sind drei verschiedene Aufzeichnungen desselben Ereignisses, und sie zu vermischen lässt einen Changelog leise von dem abdriften, was tatsächlich ausgeliefert wurde. Ein Tag markiert einen Commit. Ein Release verpackt diesen Tag mit Artefakten und einer Beschreibung. Ein Changelog-Eintrag erklärt, in Begriffen, die eine Leserin außerhalb des Repositories nutzen kann, was sich geändert hat. Sie geschehen meist zeitlich nah beieinander, und genau deshalb ist es einfach, sie als einen Schritt statt drei zu behandeln, und genau deshalb wird die Lücke erst Monate später sichtbar, wenn jemand fragt „was ist in v2.4 passiert” und die ehrliche Antwort echtes Nachgraben braucht.

Was ist der tatsächliche Unterschied zwischen den dreien?

Ein Tag ist von den dreien das mechanischste: git tag v2.4.0, und fertig, ohne dass irgendetwas erklärt werden müsste. Ein Release fügt eine Beschreibung hinzu und meist herunterladbare Artefakte, und seine Zielgruppe sind immer noch Entwicklerinnen, die wissen, was eine Release-Seite ist. Ein Changelog-Eintrag ist der einzige der drei, der für eine Leserin geschrieben ist, die das Repository vielleicht nie öffnet, weshalb er die meiste redaktionelle Aufmerksamkeit braucht und am ehesten unter Zeitdruck übersprungen wird.

Braucht jedes Git-Tag einen Changelog-Eintrag?

Nein, und die beiden 1:1 zu behandeln ist ein häufiger Fehler. Ein Tag kann einen internen Meilenstein markieren, einen Release Candidate, oder einen Hotfix, der die meisten Nutzerinnen nie erreicht; keines davon braucht zwangsläufig einen öffentlichen Eintrag. Der Test ist derselbe, der entscheidet, ob überhaupt etwas in einen Changelog gehört: Würde eine Nutzerin oder Aufruferin das bemerken oder sich dafür interessieren. Die meisten Tags bestehen diesen Test. Manche, wie ein Tag, das nur geschnitten wird, um eine CI-Pipeline auszulösen, nie.

Braucht jeder Changelog-Eintrag sein eigenes Tag?

Nicht immer, und hier unterscheiden sich Teams, die kontinuierlich deployen, von Teams, die versionierte Pakete ausliefern. Ein SaaS-Produkt, das mehrmals täglich deployt, kann mehrere Deploys unter einem datierten Changelog-Eintrag ohne 1:1-Tag pro Deploy zusammenfassen; eine Bibliothek, die in einer Paket-Registry veröffentlicht wird, braucht meist ein Tag pro veröffentlichter Version. Go-Module und der Swift Package Manager lösen Versionen direkt aus den Tags auf; bei npm oder PyPI hält die Registry die veröffentlichte Version, und das Tag ist der Weg, wie jemand diese Version ihrem Quellcode zuordnet. Ein Repository mit mehreren unabhängig versionierten Paketen muss das pro Paket entscheiden, nicht einmal für das ganze Repo; Monorepo-Changelogs behandelt, wie Tag-Präfixe und Changelog-Umfang sich an Paketgrenzen orientieren sollten statt an Ordnergrenzen. Semantic Versioning und dein Changelog behandelt, wie die Versionsnummer selbst auf Changelog-Kategorien abbilden sollte; Tags sind der Mechanismus, der eine Versionsnummer gegen den tatsächlichen Code prüfbar macht.

Wie sollte eine Release-Beschreibung mit dem Changelog-Eintrag zusammenhängen?

Sie können derselbe Text sein, aber nur, wenn die Zielgruppe für beide tatsächlich dieselbe ist, was seltener zutrifft, als es aussieht. Eine Release-Seite auf einem Code-Host wird fast ausschließlich von Entwicklerinnen gelesen; wenn ein Produkt auch nicht-technische Nutzerinnen hat, die den Changelog lesen, liefert das wortwörtliche Duplizieren der Release-Beschreibung interne Begriffe und code-orientierte Formulierung an eine Leserin, die die schlichte Sprache brauchte. Das sauberste Muster: den Changelog-Eintrag als das primäre, leserorientierte Artefakt schreiben, und die Release-Beschreibung entweder darauf verlinken lassen oder eine kürzere, technischere Zusammenfassung für die Zielgruppe halten, die dort schon zu Hause ist.

# Release v2.4.0 (GitHub, für Entwicklerinnen)
Hebt die Reports-Pipeline auf die neue Aggregations-Engine. Siehe
Changelog für die kundenorientierte Zusammenfassung:
https://example.com/changelog#v2.4.0

## 2026-09-07 (Changelog, kundenorientiert)
### Added
- Reports laden jetzt in unter einer Sekunde, selbst für Accounts mit
  mehr als einer Million Zeilen.

Dasselbe Release, zwei Dokumente, jedes mit eigener Formulierung für die eigene Leserin.

Woher kommt der Changelog-Eintrag tatsächlich?

Von zwei Startpunkten, und die meisten echten Pipelines sind eine Mischung aus beiden. Er kann zum Zeitpunkt des Tags aus Commit-Messages generiert werden, was schnell ist und nie einen gemergten Pull Request verpasst; Von Conventional Commits zum Changelog behandelt diese Pipeline vollständig. Oder er kann von Hand geschrieben werden, getrennt vom Tag, zeitlich am Moment ausgerichtet, in dem ein Feature als fertig gilt, statt am Moment, in dem Code gemergt wird. Generierte Einträge sind konsistent, erben aber jede vage Commit-Message; von Hand geschriebene Einträge sind klarer, brauchen aber jemanden, der sie tatsächlich schreibt. Die meisten Teams, die automatisieren, behalten trotzdem einen leichten Redigierschritt auf dem generierten Text, bevor er zum öffentlichen Eintrag wird, was dieselbe Disziplin ist, die Keep a Changelog, umgesetzt empfiehlt, unabhängig davon, woher der Rohtext ursprünglich stammt.

Was bricht, wenn die drei außer Sync geraten?

Das Vertrauen in das, was eine Leserin zuerst geprüft hat. Ein Tag, das ohne passenden Changelog-Eintrag existiert, sieht von der Seite der Changelog-Leserin aus, als wäre in dieser Woche nichts passiert. Ein Changelog-Eintrag ohne passendes Tag oder Release macht es unmöglich, dass jemand, der ein Produktionsproblem debuggt, genau den Code auscheckt, der live war, als ein Eintrag veröffentlicht wurde. Die Lösung ist nicht perfekte Automatisierung, sondern eine einzige Quelle der Wahrheit für die Zuordnung: ein Ort, und sei es nur die eigene Checkliste des Release-Prozesses, der sagt, dass eine ausliefer­bare Änderung alle drei bekommt, im selben Commit oder Pull Request, der sie einführt.

FAQ

Sollten Changelog-Einträge automatisch aus Git-Tags generiert werden? Sie können ein Ausgangspunkt sein, aber ein Tag allein trägt keine leserorientierte Beschreibung, nur einen Commit-Bereich. Automatisierte Generierung muss die Commit-Messages innerhalb dieses Bereichs lesen, nicht nur die Existenz des Tags, um etwas Nutzbares zu erzeugen.

Was, wenn wir nicht jedes Release taggen? Dann wird der Changelog-Eintrag zur primären Aufzeichnung, und er sollte trotzdem ein Datum und, falls das Produkt eine hat, eine Versionsnummer tragen, damit der Eintrag auch ohne passendes Tag etwas bleibt, worauf eine Leserin später verweisen kann.

Sollten Pre-Release-Tags (wie v2.4.0-rc.1) Changelog-Einträge bekommen? Generell nicht. Ein Release Candidate ist für internes oder Beta-Testen, und ein Changelog-Eintrag dafür trainiert Leserinnen darauf, Einträge für Versionen zu erwarten, die nie so ausgeliefert werden könnten. Hebe Einträge für Tags auf, die General Availability erreichen.

Kann ein einzelner Changelog-Eintrag mehrere Git-Tags abdecken? Ja, und das sollte er oft für Teams, die häufig taggen. Fasse zusammengehörige Tags unter einem datierten Eintrag zusammen, der die Netto-Änderung beschreibt, statt pro Tag einen dünnen Eintrag zu veröffentlichen, der ein Feature über mehrere Lesevorgänge zerstückelt.

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-Generator, Entwicklerdokumentation