Vorlage für Release Notes

Die Vorlage

Alles in eckigen Klammern ist ein Platzhalter. Alles andere lohnt sich zu behalten, auch die Reihenfolge: Lesende suchen nach dem, was sie betrifft, deshalb stehen Breaking Changes vorn und interne Arbeit taucht gar nicht erst auf.

## [Produkt] [Version] - [Datum]

[Ein Satz dazu, wofür dieses Release da ist. Bei Routine-Releases weglassen.]

### Breaking Changes
- [Was nicht mehr funktioniert, was stattdessen zu tun ist und bis wann.
  Verlinken Sie die Migrationsschritte.]

### Neu
- [Fähigkeit, als Ergebnis beschrieben. "Einen Filter anpinnen und
  wiederverwenden", nicht "SavedView-Modell hinzugefügt".]

### Verbessert
- [Was schneller, klarer oder zuverlässiger ist, und ungefähr um wie viel.]

### Behoben
- [Das Symptom, das die Nutzerin gesehen hat, nicht die Ursache im Code.]

Ist ein Abschnitt leer, löschen Sie die Überschrift. Ein leerer Abschnitt „Behoben“ liest sich, als wäre nichts behoben worden, und eine Überschrift ohne Inhalt lässt Lesende glauben, die Seite sei nicht vollständig geladen.

Dieselbe Vorlage, ausgefüllt

So sieht sie mit echtem Inhalt aus. Beachten Sie: Kein Eintrag nennt eine Datei, einen Branch, eine Ticketnummer oder eine Person, und der Breaking Change beginnt mit der Handlung, die die Lesenden vornehmen müssen.

## Acme API 4.2 - 20. August 2026

Die Paginierung läuft jetzt über alle List-Endpunkte hinweg cursorbasiert.

### Breaking Changes
- `?page=` entfällt auf allen List-Endpunkten. Verwenden Sie den Wert
  `nextCursor` aus der vorherigen Antwort. `?page=` liefert nach dem
  1. Oktober 2026 ein 400. Migrationsschritte:
  acme.example/docs/pagination

### Neu
- Gespeicherte Ansichten im Postfach. Einen Filter einmal anpinnen und
  aus der Seitenleiste wiederverwenden.
- Webhooks lassen sich jetzt auf ein einzelnes Projekt eingrenzen.

### Verbessert
- List-Endpunkte antworten bei großen Konten rund viermal schneller.
- Der Export-Job meldet den Fortschritt, statt hängen zu wirken.

### Behoben
- Eingeladene Mitglieder landen bis zur ersten Anmeldung nicht mehr auf
  einem leeren Dashboard.
- Zeitstempel in Exporten berücksichtigen jetzt die Zeitzone des Kontos.

Was in jeden Abschnitt gehört

Breaking Changes

Der einzige Abschnitt mit einer Frist darin. Sagen Sie, was nicht mehr funktioniert, was stattdessen zu tun ist und ab welchem Datum. Steht das Datum noch nicht fest, veröffentlichen Sie den Abschnitt noch nicht: Ein Breaking Change ohne Datum wird als dringend gelesen, und eine Folge falscher Dringlichkeit ist genau der Weg, auf dem Menschen lernen, Ihre Release Notes zu ignorieren.

Neu

Beschreiben Sie das Ergebnis, nicht das Ding, das Sie gebaut haben. Die Probe: Ergibt die Zeile noch Sinn für jemanden, der Ihre Codebasis nie gesehen hat? „Gespeicherte Ansichten im Postfach“ besteht sie. „SavedView-Modell und Migration hinzugefügt“ nicht.

Verbessert

Beziffern Sie es, wo Sie es ehrlich können. „Schneller“ ist fast nichts wert und wird abgetan; „bei großen Konten rund viermal schneller“ ist lesenswert und setzt eine Erwartung, an der Sie sich messen lassen. Wenn Sie es nicht messen können, sagen Sie in überprüfbarer Form, was besser ist.

Behoben

Schreiben Sie das Symptom, nicht die Ursache. Menschen durchsuchen diese Notizen nach dem, was ihnen passiert ist. „Eingeladene Mitglieder landeten auf einem leeren Dashboard“ ist auffindbar, „Race Condition im Membership-Cache behoben“ nicht.

Varianten

Die vier Abschnitte tragen die meisten Releases. Drei Fälle brauchen eine Anpassung:

• Mobile-App-Releases. App Stores zeigen ein kurzes Feld „Was ist neu“, beginnen Sie also mit einem Satz, den man in der Store-Ansicht lesen kann, und verlinken Sie dann die vollständigen Notizen. Die Store-Prüfung kann ein Release außerdem um Tage verzögern, datieren Sie die Notizen deshalb nach dem Release-Datum, nicht nach dem Merge-Datum.
• API-Releases. Versionieren Sie die Notizen so, wie Sie die API versionieren, und schreiben Sie das Deprecation-Fenster in die Notizen selbst, nicht nur in die Dokumentation. Wer eine API nutzt, liest die Notizen genau deshalb: um zu erfahren, wie viel Zeit bleibt.
• Interne oder Admin-Werkzeuge. Streichen Sie den Abschnitt „Verbessert“ und führen Sie ihn mit „Behoben“ zusammen. Interne Nutzende interessiert, ob sich ihr Arbeitsablauf geändert hat, und ein langer Abschnitt „Verbessert“ begräbt genau das.

Vier Regeln, die das lesbar halten

1. Schreiben Sie für jemanden, der Ihre Codebasis nicht kennt. Keine Dateinamen, keine Branch-Namen, keine Ticket-IDs, keine Servicenamen, keine internen Codenamen.
2. Lassen Sie alles weg, was für Nutzende nicht sichtbar ist. Dependency-Bumps, Refactorings, CI-Änderungen und Tippfehlerkorrekturen gehören in die Commit-Historie, nicht in Release Notes. Der häufigste Weg, auf dem Release Notes sterben, ist, dass sie sich mit Arbeit füllen, die außerhalb des Teams niemand sehen kann.
3. Ein Eintrag, eine Änderung. Braucht eine Zeile zweimal das Wort „und“, sind es vermutlich zwei Einträge.
4. Veröffentlichen Sie in einem Rhythmus, auf den man sich verlassen kann, und sei der Rhythmus „immer wenn wir ausliefern“. Notizen, die viermal in einer Woche erscheinen und dann zwei Monate nicht, gelten schnell als Rauschen.

Format für Release Notes: die Teile, der Reihe nach

Das Format zählt weniger als die Reihenfolge. Welchen Überschriftenstil Sie auch wählen, wer Release Notes überfliegt, sucht dieselben vier Dinge in derselben Abfolge, und jedes verbreitete Format für Release Notes ist eine Variation davon.

1. Eine Überschrift, die sagt, was sich für die Lesenden geändert hat, nicht die Versionsnummer. Die Version steht kleiner darunter, mit dem Datum in ISO-Form (2026-08-29), damit es sich in jedem Sprachraum gleich liest.
2. Breaking Changes und alles mit einer Frist zuerst, auch wenn es klein ist. Wenn jemand nach einem Absatz aufhört zu lesen, ist das der Absatz, den diese Person gebraucht hat.
3. Was neu ist, ein Punkt pro Absatz, mit dem Ergebnis im ersten Satzteil und der nötigen Handlung, einschließlich „nichts zu tun“, jedes Mal ausgeschrieben.
4. Behobenes und Verbessertes, danach alles Übrige als einzeilige Liste am Ende. Dependency-Bumps und interne Änderungen bleiben dort, weil die eine Person, die danach sucht, sie wirklich braucht.

In Markdown ist das eine H2-Überschrift, eine gedämpfte Zeile mit Version und Datum, dann H3-Abschnitte für Breaking, Neu, Verbessert und Behoben. In einer E-Mail ist es dieselbe Reihenfolge mit der Überschrift als Betreff. In einem Changelog-Widget sind es die Überschrift und der erste Absatz, der Rest hinter einem Link. Die Vorlage oben ist genau diese Form, ausgeschrieben.

Zum Schreiben selbst statt zur Form siehe Wie man Release Notes schreibt, die wirklich gelesen werden und Release-Notes-Best-Practices, die sich lohnen im Blog.

Häufige Fragen

Wie lang sollten Release Notes sein?

So lang wie die Änderungen, die Nutzende betreffen, und nicht länger. Ein Release mit einem Bugfix bekommt zwei Zeilen. Ein kleines Release aufzublähen, damit es gewichtig wirkt, bringt Menschen bei, über die großen hinwegzulesen.

Was ist der Unterschied zwischen Release Notes und einem Changelog?

In der Praxis werden die Begriffe synonym verwendet. Wo Teams sie unterscheiden, beschreiben Release Notes ein einzelnes Release und richten sich an Nutzende, während ein Changelog die fortlaufende Liste aller Releases über die Zeit ist. Diese Vorlage deckt ein Release ab; ein Changelog entsteht, wenn Sie sie neueste zuerst stapeln.

Sollten Release Notes eine Versionsnummer haben?

Nur wenn Ihre Nutzenden sie sehen können. Versionsnummern sind nützlich für APIs, Bibliotheken und installierte Software, wo man wissen muss, auf welcher Version man ist. Bei einer kontinuierlich ausgelieferten Web-App ist das Datum nützlicher, weil sich das mit dem eigenen Erleben abgleichen lässt.

Wer sollte sie schreiben?

Wer weiß, was sich geändert hat, also meist die Person, die es gemergt hat, redigiert von der Person, der die Tonalität gehört. Der Fehlermodus, sie ganz an jemanden außerhalb der Arbeit zu geben, sind Notizen, die das Ticket beschreiben statt der Änderung.