Bugfix-Release-Notes: Einträge, die Leute wirklich nutzen

Gute Bugfix-Release-Notes beschreiben, was die Nutzerin schiefgehen sah, nicht, was der Code falsch gemacht hat. Jeder Eintrag sagt, wer betroffen war, seit wann, ob der Fix vollständig ist und ob die Leserin etwas tun muss, selbst wenn es nur “keine Aktion nötig” ist.

Die meisten Teams kopieren eine Zeile aus der Commit-Nachricht. Die Tabelle zeigt sechs Umschreibungen, und die Abschnitte danach erklären die Regeln.

Wie schreibt man einen Bugfix-Eintrag in Release Notes?

Beginnt mit dem Symptom in den Worten der Nutzerin, dann wer betroffen war und seit wann, dann der Stand des Fixes, dann die Aktion. Ein bis zwei Sätze reichen meist. Die Ursache im Code gehört in den Pull Request, wo eine Entwicklerin danach sucht.

Eine Leserin sucht nach einer einzigen Sache: “War das ich?” Vier Teile decken fast jeden Eintrag ab:

1. Das Symptom. Was auf dem Bildschirm, in der API-Antwort oder auf der Rechnung erschien. Zitiert den Fehlertext, falls es einen gab, denn Leute suchen danach.
2. Der Umfang. Welcher Tarif, welche Plattform, API-Version oder Datenform. “Konten mit mehr als 50.000 Zeilen” ist prüfbar. “Manche Nutzer” nicht.
3. Der Zeitraum. Seit welchem Release oder Datum, damit eine Leserin entscheiden kann, ob das seltsame Ergebnis von gestern der Bug war.
4. Die Aktion. Neu starten, neu synchronisieren, aktualisieren, einen Workaround entfernen oder gar nichts.

Haben Nutzerinnen einen Workaround gebaut, ist die Aktionszeile der Ort, an dem ihr sagt, dass sie ihn löschen können.

Was ist der Unterschied zwischen einer Release Note und einem Changelog?

Ein Changelog ist die vollständige, laufende Aufzeichnung der Änderungen. Release Notes sind eine ausgewählte, neu geschriebene Nachricht zu einem Release für Menschen, die entscheiden, ob es sie interessiert. Bei Bugfixes listet der Changelog jeden Fix, und die Notes beginnen mit denen, die eine Leserin hätte bemerken können.

Ein Tippfehler in einem Tooltip gehört nur in den Changelog. Ein falscher Steuersatz auf Rechnungen gehört in beide. Die vollständige Trennung steht in Changelog vs. Release Notes, und die Form guter Notes in Wie man Release Notes schreibt.

Keep a Changelog ist eine praktische Konvention für die Aufzeichnungsseite. Sie reserviert “Fixed” für Bugfixes und eine eigene Rubrik “Security” für Schwachstellen, also dieselbe Trennung, die dieser Artikel für die Leserin macht.

Ist ein Bugfix ein Update?

Ja. Ein Bugfix verändert das Produkt, also ist seine Auslieferung ein Update. Unter Semantic Versioning ist ein abwärtskompatibler Fix ein Patch-Release, zum Beispiel 4.2.0 auf 4.2.1.

Ob die Leserin etwas tun muss, ist eine eigene Frage, und die Note sollte sie beantworten. Ein Fix, der verändert, was ein korrekter Aufrufer beobachtet, ist nah an einem Breaking Change, und Breaking Changes erklärt, wo diese Linie verläuft.

Wann bekommt ein Fix einen eigenen Eintrag, und wann ist er ein kleiner Fix?

Gebt einem Fix einen eigenen Eintrag, wenn eine Nutzerin den Bug hätte bemerken können, Zeit oder Daten daran verloren oder einen Workaround darum gebaut hat. Fasst ihn unter einer kurzen Liste “Kleine Fixes” zusammen, wenn niemand außerhalb eures Teams ihn hätte sehen können. Urteilt nach dem Erleben der Leserin, nicht nach der Größe des Diffs.

Jede Zeile in der Gruppe sollte trotzdem etwas sagen: “Einige UI-Probleme behoben” ist ein Platzhalter.

Wie schreibt man über eine Regression?

Nennt das Release, das sie eingeführt hat, bezeichnet sie als Regression und nennt das Release, das sie behebt. Wer den Bug getroffen hat, weiß schon, dass etwas kaputt war, daher dient ihm ein kurzes, direktes Eingeständnis besser als vage Formulierungen.

Zum Beispiel: “Suchergebnisse für Anfragen mit Bindestrich kamen in 4.1.0 leer zurück. Das ist in 4.1.1 behoben. Hast du deine Anfragen geändert, um Bindestriche zu vermeiden, kannst du sie zurückändern.”

“Zuverlässigkeit der Suche verbessert” liest sich für jeden, der einen Nachmittag an den Bug verloren hat, wie Ausweichen. Ist die Ursache noch nicht bestätigt, sagt das, so wie es der Leitfaden zu Notfall-Release-Notes formuliert: Lasst die Note nie sicherer klingen, als das Team ist.

Wie kündigt man einen Sicherheitsfix an?

Nennt den Schweregrad klar, die betroffenen Versionen und die Version, die sie behebt, sagt, wie dringend das Update ist, und gebt die CVE-Kennung an, falls es eine gibt. Veröffentlicht Details erst, wenn Nutzerinnen einen Fix einsetzen können, und folgt einem koordinierten Offenlegungsprozess, wenn eine Melderin beteiligt war.

Die Reihenfolge zählt: Die Melderin informiert euch privat, ihr liefert den Fix aus, und die öffentliche Note geht raus, wenn sich Nutzerinnen schützen können. CISAs Prozess zur koordinierten Offenlegung von Schwachstellen koordiniert Meldung, Analyse und öffentliche Offenlegung von Schwachstellen. Die Regeln der CVE Numbering Authority bestimmen, wie CVE-Einträge vergeben und veröffentlicht werden, und auf GitHub lässt euch ein Repository Security Advisory die Warnung privat entwerfen und eine Kennung beantragen.

Ein Sicherheitseintrag trägt meist vier Fakten:

• Was eine Angreiferin tun konnte, in einem Satz und ohne Proof of Concept.
• Betroffene Versionen und die Version, die es behebt.
• Wie dringend es ist: “Aktualisiere heute” oder “aktualisiere mit deinem nächsten Release”.
• Ob ihr Ausnutzung gesehen habt, und ein Dank an die Melderin, wenn sie zugestimmt hat.

Lasst Schritte zur Ausnutzung weg.

Was sollte eine Note zu einem Datenverlust-Fix sagen?

Sagt, welche Daten betroffen waren, woran man erkennt, ob die eigenen betroffen waren, und ob sie sich wiederherstellen lassen. “Keine Aktion nötig” stimmt hier selten, und die erste Frage der Leserin lautet “sind meine Daten weg”.

Ein brauchbarer Eintrag nennt die Bedingung, die Daten verlor (“Löschen eines Ordners während einer laufenden Synchronisierung”), den Zeitraum, in dem es möglich war, eine Prüfmöglichkeit (“öffne den Papierkorb und suche nach Einträgen vom 3. bis 9. September”) und den Weg zur Wiederherstellung. Lassen sich die Daten nicht wiederherstellen, sagt das. Kontaktiert betroffene Kundinnen außerdem direkt, denn die Release Note sollte nicht der einzige Ort sein, an dem jemand erfährt, dass seine Daten betroffen waren.

Warum ist “Fehlerbehebungen und Performance-Verbesserungen” eine schlechte Note?

Sie gibt der Leserin nichts, worauf sie reagieren kann, und versteckt die Fixes, auf die jemand gewartet hat. Eine Kundin, die einen Absturz gemeldet hat, kann nicht erkennen, ob er behoben ist, und eine Kundin mit Workaround nicht, ob sie ihn entfernen soll.

Es gibt zwei ehrliche Alternativen. Hat ein Release nichts, was eine Leserin bemerken könnte, veröffentlicht keine Notes dazu und lasst den Changelog die Aufzeichnung halten. Hat es Fixes, listet sie in den Worten der Leserin auf:

Vorher:
  Fehlerbehebungen und Performance-Verbesserungen.

Nachher:
  Behoben: CSV-Export schlug bei Projekten ohne Tags fehl.
  Behoben: Im Dunkelmodus war der Cursor im Kommentarfeld
  unsichtbar.
  Schneller: Das Dashboard öffnet schneller bei Workspaces
  mit mehr als 100 Projekten.

Woher kommen Bugfix-Notes?

Sie kommen aus dem Pull Request, der den Bug behoben hat, und aus der Meldung, die ihn ausgelöst hat. Reisen die Worte der Melderin mit dem Fix, ist das halbe Symptom schon geschrieben.

Feature Request vs. Bug Report erklärt, warum die richtige Kennzeichnung einer Meldung entscheidet, wer sie besitzt. In Changeloop wird ein über das Widget gemeldeter Bug zu einem GitHub-Issue mit dem Label bug, und der Changelog-Eintrag wird aus dem gemergten Pull Request entworfen und zur Freigabe durch einen Menschen zurückgehalten, bevor er erscheint. Die Release-Notes-Vorlage gibt euch dieselbe Eintragsform zum Schreiben von Hand: Symptom, Umfang, Zeitraum, Aktion.

FAQ

Was sollten Bugfix-Release-Notes enthalten? Jeder Eintrag sollte das Symptom nennen, das die Nutzerin sah, wer betroffen war, seit welchem Release oder Datum, ob der Fix vollständig ist und was die Leserin tun muss, einschließlich “nichts”.

Sollte jeder Bugfix in den Release Notes stehen? Nein. Listet die, die eine Nutzerin hätte bemerken können, an die sie Zeit verloren oder um die sie herumgearbeitet hat, und fasst kosmetische oder interne Fixes unter einer kurzen Liste “Kleine Fixes” zusammen. Der Changelog behält jeden Fix für alle, die einen nachschlagen müssen.

Wie schreibt man Release Notes zu einem Bug, den man selbst eingebaut hat? Sagt, dass es eine Regression war, nennt das Release, das sie eingeführt hat, und das Release, das sie behebt, und sagt den Leserinnen, ob sie einen Workaround entfernen können. Eine klare Aussage liest sich besser als weichgespülte Formulierungen.

Wie findet man die Release Notes eines Produkts, das man nutzt? Sucht nach einer Changelog- oder Release-Notes-Seite, die im Hilfemenü, in der Fußzeile oder in der Dokumentation des Produkts verlinkt ist, bei Open-Source-Projekten im Reiter Releases des Repositorys.

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: Vorlage für Release Notes