Der changeloop-Blog
Release Notes in der Praxis
Zwei Dinge beschäftigen uns sehr: wie man Release Notes schreibt, die jemand liest, und wie man Changelogs nicht mehr von Hand pflegt. Kein Newsletter, keine Registrierung. Nur die Texte.
Bugfix-Release-Notes: Einträge, die Leute wirklich nutzen
Bugfix-Release-Notes wirken, wenn jeder Eintrag Symptom, Betroffene und nächsten Schritt nennt. Mit Vorher-nachher-Beispielen und Regeln für Sicherheit.
Release Notes in der Praxis7 Min. Lesezeit
Kundenfeedback einholen: so fragt ihr in einer Software
Stellt direkt nach einer Handlung eine konkrete Frage, dort wo die Person arbeitet. Fertige Formulierungen für jeden Moment und die schlechtesten Fragen.
Feedback-Schleife7 Min. Lesezeit
Product-Roadmap-Beispiele: sechs Formate und ihr Scheitern
Sechs Product-Roadmap-Beispiele: Now/Next/Later, Quartal, Themen, Ergebnisse, öffentlich und Release. Wer sie braucht und wo sie jeweils scheitern.
Feedback-Schleife7 Min. Lesezeit
Release-Management-Prozess für Teams, die oft ausliefern
Ein Release-Management-Prozess für Softwareteams in sieben Schritten, mit Verantwortlichen und Abschlusskriterien, dazu die DORA-Metriken und mehr.
Engineering7 Min. Lesezeit
Release-Notes-Beispiele für jede Art von Änderung
Release-Notes-Beispiele für Feature, Bugfix, Breaking Change, Sicherheitsfix, Deprecation, App-Store-Text und interne Notiz, jeweils mit Begründung.
Release Notes in der Praxis7 Min. Lesezeit
Stripe-API-Versionierung: Funktionsweise und Lehren
Die Stripe-API-Versionierung bindet jedes Konto an eine datierte Version, jede Anfrage kann sie überschreiben. Was eine kleine API davon übernehmen kann.
API-Änderungen7 Min. Lesezeit
Wer schreibt den Changelog, und wer sollte
Wer schreibt den Changelog? Die PR-Autorin weiß, was sich änderte, die PM, warum es zählt. Keine allein schreibt einen Eintrag, der Kunden etwas nützt.
Engineering5 Min. Lesezeit
Notfall-Release-Notes: Schreiben unter echtem Zeitdruck
Ein durch einen Incident ausgelöstes Release braucht Notes in Minuten, nicht Tagen, und der übliche Schreibprozess setzt Zeit voraus, die man nicht hat.
Release Notes in der Praxis5 Min. Lesezeit
Protobuf-Breaking-Changes: was auf dem Wire überlebt
Protobuf-Breaking-Changes passieren auf dem Wire, nicht in der URL. Manche gRPC-Feldänderungen sind kostenlos, andere brechen jeden Client lautlos.
API-Änderungen6 Min. Lesezeit
Changelog-Dateiformate: JSON, YAML oder einfach Markdown
Das Dateiformat eines Changelogs entscheidet, ob er eine Seite speisen kann oder nur Menschen dient. Markdown, JSON und YAML kosten jeweils anderes.
Engineering5 Min. Lesezeit
Doppelte Feature-Requests: Ohne die Stimme zu verlieren
Doppelte Feature-Requests zu gruppieren schützt die Zählung. Unachtsames Zusammenführen verliert die Formulierung, die einen davon nützlich machte.
Feedback-Schleife5 Min. Lesezeit
GraphQL-Abkündigung ohne Versionsnummer
GraphQL hat kein v1 oder v2 in der URL. Felder werden einzeln per Direktive abgekündigt, auf einem geteilten Schema. Was ein Changelog hier schuldet.
API-Änderungen5 Min. Lesezeit
Wie man einen API-Migrationsleitfaden schreibt
Ein API-Migrationsleitfaden macht aus einer Breaking Change eine Checkliste statt eines Ausfalls. Was er braucht und warum ein Eintrag allein nicht reicht.
API-Änderungen5 Min. Lesezeit
Ein Changelog-Check für GitHub Actions
Ein Changelog-Check in GitHub Actions blockiert Merges ohne Eintrag, weil ein Schritt, der auf Erinnerung setzt, scheitert. Und was der Check kaputt macht.
Engineering5 Min. Lesezeit
Feature-Request ablehnen, ohne die Kundin zu verlieren
Die Schleife zu schließen heißt meist: ausgeliefert. Die schwerere Hälfte ist Nein zu sagen, ohne dabei die Beziehung zur Kundin zu beschädigen.
Feedback-Schleife5 Min. Lesezeit
Feature-Flag-Release-Notes: was man sagt, und wann
Feature-Flag-Release-Notes müssen Merge und Auslieferung trennen. Wer die Schleife zum falschen Zeitpunkt schließt, kündigt ein unsichtbares Feature an.
Feedback-Schleife5 Min. Lesezeit
Feature-Request-Tracking, ohne Anfragen zu verlieren
Feature-Request-Tracking scheitert meist auf zwei Arten: Anfragen landen nirgends oder dort, wo niemand mehr nachschaut. Ein System, das beides übersteht.
Feedback-Schleife5 Min. Lesezeit
Wenn ein Feature-Request eigentlich ein Bug-Report ist
Ein Support-Ticket, das eine neue Einstellung wünscht, kann ein Workaround für einen verdeckten Bug sein. Das falsche Label führt in die falsche Queue.
Feedback-Schleife5 Min. Lesezeit
Support-Tickets vs. Feature-Requests: Wem Vertraut Ihr?
Ein Support-Ticket und ein Feature-Request-Board messen Verschiedenes. Einen Anstieg im einen wie im anderen zu behandeln, ergibt falsche Prioritäten.
Feedback-Schleife5 Min. Lesezeit
Git-Tags, Releases und dein Changelog
Ein Git-Tag, ein Release, ein Changelog-Eintrag: drei Aufzeichnungen desselben Ereignisses. Vermischt man sie, driftet der Changelog vom Ausgelieferten ab.
Engineering5 Min. Lesezeit
Interne API-Changelogs: Was sich für das andere Team ändert
Ein öffentlicher API-Changelog hat ein Publikum, das man nicht direkt erreicht. Ein interner hat es zwei Stockwerke weiter, und das ändert einiges.
API-Änderungen5 Min. Lesezeit
Interne Release Notes: Wer noch wissen muss, was kam
Support und Vertrieb erfahren von einem Launch meist durch eine verwirrte Kundin. Interne Release Notes beheben das, in anderer Form als kundenseitige.
Release Notes in der Praxis5 Min. Lesezeit
Release Notes für Mobile Apps: Was das Limit streicht
App Store und Play Store geben ein paar sichtbare Zeilen und keine Links. Was in einem Web-Changelog funktioniert, scheitert an diesem Budget.
Release Notes in der Praxis4 Min. Lesezeit
Monorepo-Changelogs: Einer, oder einer pro Paket?
Ein Monorepo kann ein Changelog fürs ganze Repo führen oder eines pro Paket, und die falsche Wahl macht jeden Release zu unübersichtlich oder zu verstreut.
Engineering5 Min. Lesezeit
Wie man ein neues Feature ankündigt (ohne Stille)
Die meisten Feature-Ankündigungen sterben in einem ungelesenen Kanal. Wo man ankündigt, was zuerst gesagt wird, und wie man die richtigen Leute erreicht.
Release Notes in der Praxis5 Min. Lesezeit
Feature-Requests priorisieren, wenn der Stapel wächst
Ein Backlog lässt die schwere Frage offen: welcher Request kommt als Nächstes. Die Frameworks, wo jedes bricht, und was eine rohe Stimmenzahl verbirgt.
Feedback-Schleife5 Min. Lesezeit
Enterprise Release Notes: was sich für einen Account ändert
Enterprise Release Notes für Kunden auf privaten Builds müssen zur Instanz passen. Falsch zugeschnitten verraten sie die Roadmap oder verwirren Support.
Release Notes in der Praxis5 Min. Lesezeit
Semantic Versioning und dein Changelog
Semantic Versioning sagt, wie sehr ein Release wehtun kann, vor dem ersten Wort im Changelog. Was jede Zahl verspricht, und was ein Eintrag dafür schuldet.
Engineering5 Min. Lesezeit
Der API-Sunset-Header, und wann man ihn sendet
Der API-Sunset-Header sagt einem Client, wann eine Version verstummt, anders als eine Deprecation-Ankündigung. Was RFC 8594 regelt, was Brownouts bringen.
API-Änderungen5 Min. Lesezeit
Webhook-Changelogs: Der Breaking Change, den niemand wollte
Eine Webhook-Payload-Änderung bricht lautlos, weil kein Aufrufer die neue Form ablehnen kann. Was dabei als Breaking Change zählt, und wie man versioniert.
API-Änderungen5 Min. Lesezeit
Changelog: Was ist das? Mit Beispiel-Eintrag
Ein Changelog ist das datierte Protokoll der Änderungen an einem Produkt. Mit Beispiel-Eintrag, dem Unterschied zu Release Notes und wo er hingehört.
Release Notes in der Praxis5 Min. Lesezeit
API-Changelog: was hinein gehört und wer es liest
Ein API-Changelog lesen Leute, die entscheiden, ob ihr Code nächsten Monat noch läuft. Was jeder Eintrag schuldet, wo er lebt und wie man ihn abonniert.
API-Änderungen6 Min. Lesezeit
Wie man eine Changelog-Seite baut, die man abonniert
Eine Changelog-Seite lohnt sich, wenn jemand zurückkehrt. Wo sie leben sollte, was ein Eintrag braucht, Feeds und Markup, und wie das Widget dazu passt.
Engineering6 Min. Lesezeit
Die Produkt-Update-E-Mail-Vorlage, die gelesen wird
Die Produkt-Update-E-Mail, die gelesen wird, ging an jemanden, der danach fragte. Eine Vorlage, vier Arten von Update-Mails, Betreffzeilen, Einwilligung.
Release Notes in der Praxis6 Min. Lesezeit
Wie man eine API abkündigt, ohne Entwickler zu verlieren
Deprecation ist ein Versprechen mit Datum. Der Zeitplan, die Ankündigungsvorlage, die Response-Header, und der Schritt gegen einen Sunset-Vorfall.
API-Änderungen6 Min. Lesezeit
API-Versionierung: Best Practices im Sinne der Aufrufer
Versioniert nur, was bricht. Platziert die Version sichtbar, und haltet die alte Version bis zu einem Datum am Laufen. Vier Schemata im Vergleich.
API-Änderungen7 Min. Lesezeit
Breaking Changes: was zählt und wie man sie ausliefert
Ein Breaking Change ist jede Änderung, die ein korrekter Aufrufer nicht überlebt. Was zählt, was nicht, wie man ihn in CI erkennt und sicher ausliefert.
API-Änderungen9 Min. Lesezeit
Den Feedback-Loop vom Changelog aus schließen
Ein Feedback-Loop schließt, wenn der Fragende erfährt: ausgeliefert. Vier Schritte, wo er meist bricht, und warum der Changelog der richtige Ort dafür ist.
Feedback-Schleife8 Min. Lesezeit
Feature-Request-Vorlage, die zum Changelog-Eintrag wird
Eine Feature-Anfrage nützt nur, wenn man sie beim Release wiederfindet. Die Vorlage, die Labels fürs Routing und die Felder, die der Changelog liest.
Feedback-Schleife6 Min. Lesezeit
Öffentliche Roadmap aus dem Issue-Tracker, drei Spalten
Eine öffentliche Roadmap ist ein Versprechen über die Zukunft. Haltet sie klein, speist sie aus euren Issues und bewegt jeden Punkt per Label am Issue.
Feedback-Schleife6 Min. Lesezeit
Changelog-Automatisierung und ihre Grenzen
Automatisiere Sammeln, Formatieren und Veröffentlichen. Nicht Auswahl oder Formulierung. Wo die Grenze liegt und was bei jeder Verschiebung passiert.
Engineering6 Min. Lesezeit
Changelog vs. Release Notes: Was ist der Unterschied?
Ein Changelog ist ein laufendes Verzeichnis zum Nachschlagen. Release Notes sind eine kuratierte Botschaft für Leute, die entscheiden, ob es sie betrifft.
Release Notes in der Praxis5 Min. Lesezeit
Von Conventional Commits zum Changelog
Conventional Commits machen einen Changelog ableitbar, aber nicht lesbar. Was die Konvention bringt, wo sie aufhört und wie man die Lücke schließt.
Engineering5 Min. Lesezeit
Wie man Release Notes schreibt, die wirklich gelesen werden
Bugfixes und Performance-Verbesserungen sind keine Release Note. Die Frage, die jeder Eintrag beantworten muss, plus eine echte Vorher-Nachher-Fassung.
Release Notes in der Praxis6 Min. Lesezeit
Keep a Changelog, tatsächlich umgesetzt
Die Keep-a-Changelog-Spezifikation ist eine Seite lang. Bei der Umsetzung driften Teams ab. Was sie sagt, was sie offenlässt und wo es schiefgeht.
Engineering5 Min. Lesezeit
Release-Notes-Best-Practices, die sich lohnen
Die meisten Best-Practice-Listen für Release Notes sind Stilratschläge. Diese hier ändern, was Leserinnen tun, plus drei populäre, die reiner Kult sind.
Release Notes in der Praxis5 Min. Lesezeit