Bugfix release notes schrijven die mensen gebruiken

Goede bugfix release notes beschrijven wat de gebruiker zag misgaan, niet wat de code verkeerd deed. Elke entry zegt wie getroffen was, sinds wanneer, of de fix volledig is en of de lezer iets moet doen, al is dat alleen “geen actie nodig”.

De meeste teams kopiëren een regel uit het commitbericht. De tabel toont zes herschrijvingen, en de secties erna leggen de regels uit.

Hoe schrijf je een bugfix-entry in release notes?

Begin met het symptoom in de woorden van de gebruiker, dan wie getroffen was en sinds wanneer, dan de stand van de fix, dan de actie. Een of twee zinnen dekken het meestal. De oorzaak in de code hoort in de pull request, waar een engineer ernaar zoekt.

Een lezer scant op één ding: “was dit mij?” Vier onderdelen dekken bijna elke entry:

1. Het symptoom. Wat op het scherm verscheen, in het API-antwoord of op de factuur. Citeer de fouttekst als die er was, want mensen zoeken erop.
2. Het bereik. Welk plan, welk platform, welke API-versie of welke vorm van data. “Accounts met meer dan 50.000 rijen” is controleerbaar. “Sommige gebruikers” niet.
3. Het venster. Sinds welke release of datum, zodat een lezer kan beslissen of het vreemde resultaat van gisteren de bug was.
4. De actie. Opnieuw draaien, opnieuw synchroniseren, upgraden, een workaround verwijderen, of helemaal niets.

Als gebruikers een workaround hebben gebouwd, is de actieregel de plek om ze te vertellen dat ze die kunnen weggooien.

Wat is het verschil tussen een release note en een changelog?

Een changelog is het complete, doorlopende register van wijzigingen. Release notes zijn een geselecteerd, herschreven bericht over één release voor mensen die beslissen of het hen aangaat. Bij bugfixes noemt de changelog elke fix en openen de notes met de fixes die een lezer kon hebben opgemerkt.

Een typfout in een tooltip hoort alleen in de changelog. Een verkeerd btw-tarief op facturen hoort in beide. De volledige scheiding staat in changelog vs release notes, en de vorm van een goede set notes in hoe schrijf je release notes.

Keep a Changelog is een handige conventie voor de registerkant. Het bewaart “Fixed” voor bugfixes en een aparte kop “Security” voor kwetsbaarheden, wat dezelfde scheiding is die dit artikel voor de lezer maakt.

Is een bugfix een update?

Ja. Een bugfix verandert het product, dus het uitbrengen ervan is een update. Onder semantic versioning is een achterwaarts compatibele fix een patchrelease, bijvoorbeeld 4.2.0 naar 4.2.1.

Of de lezer iets moet doen is een aparte vraag, en de note moet die beantwoorden. Een fix die verandert wat een correcte aanroeper waarneemt, ligt dicht bij een breaking change, en breaking changes legt uit waar die grens ligt.

Wanneer krijgt een fix een eigen entry, en wanneer is het een kleine fix?

Geef een fix een eigen entry wanneer een gebruiker de bug kon opmerken, er tijd of data aan kwijtraakte of er een workaround omheen bouwde. Groepeer hem onder een korte lijst “Kleine fixes” wanneer niemand buiten je team hem kon zien. Beoordeel het naar de ervaring van de lezer, wat de omvang van de diff ook is.

Elke regel in de groep moet nog steeds iets zeggen: “Een paar UI-problemen opgelost” is een plaatshouder.

Hoe schrijf je over een regressie?

Noem de release die haar veroorzaakte, noem het een regressie en geef de release die haar oplost. Mensen die de bug tegenkwamen weten al dat het kapot was, dus een korte, directe erkenning dient hen beter dan vage bewoordingen.

Bijvoorbeeld: “Zoekresultaten voor zoekopdrachten met een koppelteken kwamen leeg terug in 4.1.0. Dit is opgelost in 4.1.1. Als je je zoekopdrachten hebt aangepast om koppeltekens te vermijden, kun je ze terugzetten.”

“Verbeterde betrouwbaarheid van zoeken” leest als ontwijken voor iedereen die een middag aan de bug kwijt was. Als de oorzaak nog wordt bevestigd, zeg dat dan, zoals de richtlijn over noodrelease notes het zegt: laat de note nooit zekerder klinken dan het team is.

Hoe kondig je een beveiligingsfix aan?

Noem de ernst duidelijk, noem de getroffen versies en de versie die ze oplost, zeg hoe dringend de upgrade is en neem de CVE-identifier op als die er is. Publiceer details pas zodra gebruikers een fix kunnen toepassen, volgens een gecoördineerd disclosureproces wanneer er een melder bij betrokken was.

De volgorde telt: de melder vertelt het je privé, jij brengt de fix uit, en de publieke note gaat uit wanneer gebruikers zichzelf kunnen beschermen. Het gecoördineerde disclosureproces van CISA coördineert melding, analyse en publieke bekendmaking van kwetsbaarheden. De CVE Numbering Authority-regels bepalen hoe CVE-records worden toegekend en gepubliceerd, en op GitHub laat een repository security advisory je het advies privé opstellen en een identifier aanvragen.

Een beveiligingsentry bevat meestal vier feiten:

• Wat een aanvaller kon doen, in één zin en zonder proof of concept.
• Getroffen versies, en de versie die het oplost.
• Hoe dringend het is: “upgrade vandaag” of “upgrade bij je volgende release”.
• Of je misbruik hebt gezien, en een vermelding van de melder als die akkoord ging.

Laat exploitstappen weg.

Wat moet een note zeggen over een fix voor dataverlies?

Zeg welke data getroffen was, hoe je kunt zien of die van jou erbij zat en of ze te herstellen is. “Geen actie nodig” is hier zelden waar, en de eerste vraag van de lezer is “is mijn data weg”.

Een bruikbare entry geeft de voorwaarde waaronder data verloren ging (“een map verwijderen terwijl een synchronisatie liep”), het venster waarin dat kon, een manier om het te controleren (“open Prullenbak en zoek naar items van 3 tot 9 september”) en het herstelpad. Als de data niet te herstellen is, zeg dat. Neem ook rechtstreeks contact op met getroffen klanten, want de release note mag niet de enige plek zijn waar iemand hoort dat zijn data geraakt is.

Waarom is “Bugfixes en prestatieverbeteringen” een slechte note?

Het geeft de lezer niets om op te handelen en verbergt de fixes waar iemand op wachtte. Een klant die een crash meldde kan niet zien of die is opgelost, en een klant met een workaround kan niet zien of die weg mag.

Er zijn twee eerlijke alternatieven. Heeft een release niets wat een lezer kon opmerken, publiceer dan geen notes en laat de changelog het register vasthouden. Heeft hij fixes, som ze dan op in de termen van de lezer:

Voor:
  Bugfixes en prestatieverbeteringen.

Na:
  Opgelost: CSV-export faalde voor projecten zonder tags.
  Opgelost: donkere modus verborg de cursor in het
  reactieveld.
  Sneller: het dashboard opent sneller voor workspaces
  met meer dan 100 projecten.

Waar komen bugfix-notes vandaan?

Ze komen uit de pull request die de bug oploste en de melding die hem aanzette. Als de woorden van de melder met de fix meereizen, is het halve symptoom al geschreven.

Featureverzoek of bug legt uit waarom het juist labelen van een melding bepaalt wie eigenaar is. In Changeloop wordt een bug die via de widget is gemeld een GitHub-issue met het label bug, en de changelog-entry wordt opgesteld uit de gemergede pull request en vastgehouden tot een persoon hem goedkeurt voordat hij wordt gepubliceerd. De release notes template geeft je dezelfde entryvorm om met de hand te schrijven: symptoom, bereik, venster, actie.

FAQ

Wat moeten bugfix release notes bevatten? Elke entry moet het symptoom noemen dat de gebruiker zag, wie getroffen was, sinds welke release of datum, of de fix volledig is en wat de lezer moet doen, inclusief “niets”.

Moet elke bugfix in de release notes staan? Nee. Noem de fixes die een gebruiker kon opmerken, waar hij tijd aan kwijtraakte of omheen werkte, en groepeer cosmetische of interne fixes onder een korte lijst “Kleine fixes”. De changelog bewaart elke fix voor wie er een moet opzoeken.

Hoe schrijf je release notes voor een bug die je zelf introduceerde? Zeg dat het een regressie was, noem de release die hem veroorzaakte en de release die hem oplost, en vertel lezers of ze een workaround kunnen verwijderen. Een gewone mededeling leest beter dan afgezwakte bewoordingen.

Hoe bekijk je de release notes van een product dat je gebruikt? Zoek een changelog- of release notes-pagina die gelinkt is vanuit het helpmenu, de footer of de documentatie van het product, of in het tabblad releases van de repository bij open-sourceprojecten.

De technische beweringen in dit artikel zijn niet onafhankelijk gecontroleerd. Klopt er iets niet, laat het ons weten, dan corrigeren we het.

Meer op changeloop: Sjabloon voor release notes