Changelog und Release Notes schreiben, die Kunden wirklich lesen
Sie haben im letzten Monat ein Dutzend Dinge ausgeliefert. Ihr Changelog sagt: „Fehlerbehebungen und Leistungsverbesserungen.“
Kunden, die auf eine dieser Korrekturen gewartet haben, ahnen nicht, dass sie da ist. Der Interessent, der Sie mit einem Wettbewerber vergleicht, sieht ein Produkt, das sich seit dem Frühjahr scheinbar nicht bewegt hat.
So schreiben Sie einen Changelog, den Menschen wirklich lesen. Schreiben Sie für den Kunden, nicht für die Person, die den Code gemergt hat. Datieren Sie jeden Eintrag. Gruppieren Sie Änderungen unter Neu, Verbessert und Behoben. Stellen Sie in jedem Eintrag voran, was jemand jetzt tun kann, ergänzen Sie eine Zeile dazu, warum es wichtig ist, und sagen Sie, wo man es findet. Lassen Sie alles weg, was ein Kunde nicht sehen kann, und alles, was noch nicht live ist. Veröffentlichen Sie dann in einem gleichmäßigen Rhythmus, auch wenn manche Wochen kurz ausfallen.
Das ist das meiste. Der Rest dieses Beitrags besteht aus einer Vorlage, einer Reihe von Beispielen für schlechte und gute Einträge und einer Routine, mit der Sie von gemergten PRs zu veröffentlichten Notizen kommen, ohne dass es Ihren Freitag auffrisst.
Changelog oder Release Notes: Was ist der Unterschied?
Die Begriffe werden synonym verwendet, aber es gibt eigentlich zwei Zielgruppen.
Ein Entwickler-Changelog ist meist eine CHANGELOG.md im Repository. Er richtet sich an Menschen, die Ihre API, Ihr SDK oder Ihre Bibliothek einbinden. Ihnen sind Versionsnummern, Breaking Changes und Deprecations wichtig. Keep a Changelog ist hier die Standardreferenz, und seine Konventionen sind vernünftig: neueste Einträge zuerst, ein Abschnitt pro Version, Änderungen gruppiert als Added, Changed, Deprecated, Removed, Fixed und Security, und ein Abschnitt „Unreleased“ ganz oben für Arbeit, die gemergt, aber noch nicht ausgeliefert ist.
Release Notes (oder „Produkt-Updates“ oder eine öffentliche Changelog-Seite) richten sich an Kunden, die das Produkt nutzen. Ihnen ist egal, dass Sie eine Abhängigkeit aktualisiert haben. Sie wollen wissen, was sie jetzt tun können, das letzte Woche nicht ging.
Wenn Sie ein SaaS-Produkt betreiben, brauchen Sie wahrscheinlich eher Letzteres als Ersteres. Viele Teams brauchen beides, und das ist in Ordnung: Eine Liste gemergter Arbeit kann zwei Texte speisen. Veröffentlichen Sie nur nicht die Entwicklerversion und nennen sie Release Notes.
Eine Vorlage für Release Notes zum Kopieren
Sie funktioniert für ein wöchentliches oder zweiwöchentliches Produkt-Update, auf einer Changelog-Seite, in einem Widget in der App oder als E-Mail.
## 6 October 2026
### New
**[What you can now do, in plain words]**
[One or two sentences: what it does and who it's for.]
Find it in **[Page > Section]**. [Link to help article]
### Improved
**[The thing that got better]**
[What's different from before, in terms the customer notices:
faster, fewer clicks, works on mobile, handles bigger files.]
### Fixed
- [Symptom the customer saw], now fixed.
- [Symptom the customer saw], now fixed.
### Heads up (only if needed)
**[Anything changing or going away]**
[What's happening, when, and what they need to do.]
Ein paar Regeln, damit es funktioniert:
- Titel beschreiben das Ergebnis, nicht den Namen der Funktion. „Große Berichte ohne Zeitüberschreitung exportieren“ schlägt „Async CSV export“.
- Korrekturen beschreiben das Symptom. Kunden erinnern sich an „Die Summen waren um einen Tag verschoben“, nicht an „Zeitzonenbehandlung im Aggregations-Job“.
- Verlinken Sie den Hilfeartikel bei allem, was neu ist. Der Changelog sagt, dass etwas existiert, der Artikel sagt, wie man es nutzt. Wenn Sie noch keinen geschrieben haben: Unser Leitfaden zum Schreiben von Hilfeartikeln hat auch dafür eine Vorlage.
- Stellen Sie die Änderung voran, die die meisten interessiert, auch wenn sie nicht die aufwendigste war.
Schlechte und gute Changelog-Einträge
Der häufigste Fehler ist das Einfügen von Commit-Nachrichten. So sieht das aus:
v2.14.0
- feat(export): csv async job
- fix: tz bug in reports
- refactor billing svc
- bump deps
- misc improvements
Alles darin stimmt. Nichts davon ist für einen Kunden nützlich. Zwei Einträge sind internes Rauschen, einer ist bedeutungslos („misc improvements“), und die zwei echten Änderungen sind für den geschrieben, der den PR geprüft hat.
Hier dasselbe Release, umgeschrieben:
6 October
NEW: Big CSV exports run in the background
Exports over 10,000 rows no longer time out. Start the export
and we'll email you a link when the file is ready.
Find it in Reports > Export.
FIXED: Report dates now match your timezone
Daily totals were splitting at midnight UTC instead of your
local midnight, so some days looked short. They're correct now,
including for past reports.
Zwei Einträge statt fünf. Jeder sagt, was sich geändert hat, warum der Leser sich dafür interessieren sollte und wo er nachsehen kann. Das Refactoring und das Update der Abhängigkeiten sind verschwunden, weil kein Kunde sie bemerken wird.
Noch ein paar Paare, denn das Muster braucht eine Weile, bis es zur Gewohnheit wird:
| Schlecht | Gut |
|---|---|
| SSO hinzugefügt | Mit Okta oder Google Workspace anmelden. Admins können es unter Einstellungen > Sicherheit aktivieren. |
| Leistung verbessert | Das Dashboard lädt bei großen Konten deutlich schneller. Projekte mit Tausenden von Elementen hängen beim ersten Laden nicht mehr. |
| Fehler bei Benachrichtigungen behoben | Sie erhalten keine doppelten E-Mails mehr, wenn Sie in einem Kommentar zweimal erwähnt werden. |
| v1-Endpunkte als veraltet markiert | Die v1-API funktioniert ab dem 1. März nicht mehr. Wechseln Sie vorher zu v2. Das ändert sich. |
Beachten Sie, dass „deutlich schneller“ vage ist. Wenn Sie eine echte Zahl gemessen haben, nennen Sie sie. Wenn nicht, beschreiben Sie das Erlebnis, statt eine Prozentzahl zu erfinden.
Einen Changelog aus gemergten PRs schreiben
Die meisten Teams tun sich nicht mit dem Schreiben schwer. Sie tun sich schwer damit, sich zu erinnern, was ausgeliefert wurde. Hier eine Routine, die trägt.
1. Sammeln. Listen Sie alles auf, was seit dem letzten Eintrag gemergt wurde. Mit der GitHub CLI:
gh pr list --state merged \
--search "merged:>=2026-10-27" \
--json number,title,labels,mergedAt,url \
--limit 100
2. Filtern. Stellen Sie bei jedem PR zwei Fragen. Kann ein Kunde das sehen oder spüren? Ist es für ihn tatsächlich live? Interne Refactorings, CI-Änderungen und Testkorrekturen fallen weg. Ebenso alles hinter einem Feature-Flag, das noch nicht eingeschaltet ist. Arbeit anzukündigen, auf die Kunden noch nicht zugreifen können, ist schlimmer als sie nicht anzukündigen, denn Sie bekommen Tickets mit „Wo ist das?“.
3. Gruppieren. Ordnen Sie den Rest in Neu, Verbessert und Behoben. Mehrere kleine PRs ergeben oft zusammen einen Eintrag („Massenbearbeitung“ können vier PRs sein).
4. Umschreiben. Machen Sie aus jeder Gruppe mit der Vorlage einen Eintrag. Nutzen zuerst, klare Worte, wo man es findet.
5. Veröffentlichen und verlinken. Veröffentlichen Sie, verlinken Sie jede neue Funktion mit ihrem Hilfeartikel und teilen Sie den Eintrag überall dort, wo Ihre Kunden ihn sehen.
Der Trick, der Schritt 4 deutlich leichter macht, ist, den Satz für den Kunden schon beim PR einzufordern, solange der Autor noch weiß, was er gebaut hat. Fügen Sie einen Abschnitt zu .github/pull_request_template.md hinzu:
## Customer-facing change
<!-- One sentence a customer would understand, or "None". -->
<!-- e.g. "You can now export reports over 10,000 rows." -->
- [ ] Behind a feature flag (don't announce until it's on)
- [ ] Help articles checked
Dieses letzte Kästchen ist wichtig. Jede ausgelieferte Änderung, die die Oberfläche berührt, kann einen Hilfeartikel veralten lassen, und der Changelog ist ein guter Moment, das aufzufangen. Diese Seite behandeln wir in Dokumentation aktuell halten.
Wie oft sollten Sie Produkt-Updates veröffentlichen?
Orientieren Sie sich in vernünftigem Rahmen an Ihrem Auslieferungsrhythmus. Wenn Sie kontinuierlich ausliefern, liest sich eine wöchentliche oder zweiwöchentliche Zusammenfassung besser als ein Eintrag pro Deployment. Wenn Sie monatlich ausliefern, veröffentlichen Sie monatlich.
Wichtiger als die Häufigkeit ist die Beständigkeit. Ein Changelog mit drei Einträgen im Januar und nichts seitdem sagt Besuchern etwas, das Sie wahrscheinlich nicht sagen wollten. Eine kurze Woche ist in Ordnung. „Diese Woche zwei Korrekturen, nächste Woche ein größeres Release“ ist besser als Schweigen.
Große Launches verdienen mehr als eine Zeile im Changelog: eine richtige Ankündigung, eine E-Mail, vielleicht ein kurzes Video. Der Changelog ist das laufende Protokoll, nicht der ganze Marketingplan.
Wo Sie Ihren Changelog platzieren
- Eine öffentliche Seite unter
/changelogoder/updates. Gut für Interessenten und für die Suche. - In der App, als Link oder Widget „What’s new“. Hier sehen bestehende Nutzer ihn tatsächlich.
- Per E-Mail, als monatliche Zusammenfassung für alle, die sich dafür angemeldet haben.
- Im Repository, als
CHANGELOG.md, wenn Entwickler Sie einbinden.
Spezialisierte Tools wie Beamer, Headway, LaunchNotes oder der Changelog von Canny decken die Widget- und E-Mail-Seite gut ab. Viele Teams nutzen einfach eine Seite auf ihrer Dokumentations-Website. Das Tool zählt weniger als die Gewohnheit.
Wo Ellie Docs ins Spiel kommt
Offenlegung: Für dieses Problem haben wir etwas gebaut. Ellie Docs beobachtet Ihre gemergten PRs und entwirft daraus Changelog-Einträge, die für Kunden statt für Reviewer geschrieben sind. Es hält Einträge zu Arbeit zurück, die unveröffentlicht ist oder hinter einem Flag liegt, damit Sie nichts ankündigen, was Menschen nicht nutzen können. Sie bearbeiten, verwerfen oder veröffentlichen jeden Eintrag. Nichts geht von allein raus.

Weil es auch Ihr Help-Center pflegt, erzeugt derselbe PR, der einen Changelog-Eintrag liefert, einen Änderungsvorschlag für jeden Artikel, der dadurch veraltet ist, dargestellt als Diff, den Sie annehmen oder verwerfen.

Wenn Ihr Changelog derzeit eine Liste von Commit-Titeln ist oder seit dem Launch nicht angefasst wurde, füllt es genau diese Lücke. Wenn Sie ihn gern von Hand schreiben, bringen Sie die Vorlage und die PR-Checkliste oben schon ein gutes Stück weit.
Ein paar häufige Fragen
Sollte ein Changelog Fehlerbehebungen enthalten? Ja, die, die Kunden bemerkt haben. Die Korrektur eines gemeldeten Fehlers gehört zu den meistgelesenen Dingen, die Sie veröffentlichen können, besonders wenn Sie der Person Bescheid geben, die ihn gemeldet hat. Lassen Sie Korrekturen weg, die außerhalb des Teams nie jemand gesehen hat.
Brauche ich Versionsnummern? Für eine API, ein SDK oder alles, was installiert wird, ja, und folgen Sie Semantic Versioning, damit Menschen das Risiko auf einen Blick beurteilen können. Für eine Web-App, die kontinuierlich deployt wird, sind Datumsangaben klarer. Kunden denken nicht in Versionen.
Wie lang sollte ein Changelog-Eintrag sein? Ein fetter Titel plus ein bis drei Sätze. Wenn Sie mehr brauchen, schreiben Sie einen Hilfeartikel oder einen Blogbeitrag und verlinken Sie ihn.
Möchten Sie Ihren Changelog aus den PRs entwerfen lassen, die Sie bereits gemergt haben? Testen Sie Ellie Docs kostenlos. Es gibt einen kostenlosen Tarif, ohne Karte.