Beste practices voor release notes die het waard zijn
6 min lezen bijgewerkt op
De beste practices voor release notes die ertoe doen zijn die met een gevolg eraan vast: schrijf de entry bij het mergen, noem wie het treft, vermeld de vereiste actie ook als het er geen is, geef breaking changes een datum, houd één permanente entry per verandering, groepeer op resultaat, en houd de saaie sectie. Elk daarvan verandert wat een lezer doet. De meeste andere adviezen over dit onderwerp veranderen hoe de notes eruitzien.
Zoek naar beste practices voor release notes en je krijgt stijladvies: wees duidelijk, wees beknopt, gebruik gewone taal, voeg screenshots toe. Niets daarvan is fout en niets daarvan verandert iets, want geen enkel team is ooit gaan zitten met de bedoeling onduidelijk te zijn. De practices hieronder gaan vergezeld van wat het kost om ze over te slaan, want een practice zonder gekoppeld faalscenario is slechts een voorkeur.
| Practice | Wat het kost om over te slaan |
|---|---|
| De entry schrijven bij de merge, niet bij de release | Later gereconstrueerde entries zeggen “diverse verbeteringen” |
| Noem wie het treft | Elke lezer besluit dat het niet op hem van toepassing is |
| Vermeld de vereiste actie, inclusief “geen” | Veertig identieke supporttickets, en lezers die het ergste aannemen |
| Dateer breaking changes, versie ze niet | De deadline wordt ontdekt nadat hij verstreken is |
| Eén permanente, koppelbare entry per verandering | Niemand kan antwoorden “wanneer is dit veranderd” |
| Groepeer op resultaat, niet op systeem | Lezers hebben jullie architectuur nodig om hun sectie te vinden |
| Houd de saaie sectie | Security, compliance en wie een versiemismatch debugt verliezen hun bron |
Wat zijn de beste practices voor release notes?
Schrijf de entry als je mergt, niet als je uitbrengt. Kosten van overslaan: wie de release reconstrueert uit de commit-geschiedenis is niet degene die de verandering maakte, en die zal het opzet raden. Entries die twee weken later worden geschreven zijn degene die “diverse verbeteringen” zeggen.
Zeg wie het treft, bij naam. “Teams op het Business-plan”, “iedereen die de v1-export-API gebruikt”, “self-hosted installaties op Postgres 14”. Kosten van overslaan: elke lezer moet uitzoeken of het op hem van toepassing is, en de meesten zullen besluiten van niet.
Vermeld de vereiste actie, ook als het er geen is. Kosten van overslaan: support beantwoordt dezelfde vraag veertig keer, en de lezers die niet vroegen nemen aan dat er iets vereist is en stellen het uit.
Geef breaking changes een datum, geen releasenummer. “Verwijderd in v5” betekent niets voor iemand die niet weet wanneer v5 uitkomt. “Werkt niet meer vanaf 1 november” betekent voor iedereen hetzelfde. Kosten van overslaan: de deadline wordt ontdekt nadat hij verstreken is. Wat als zodanig telt, en de checklist om het uit te brengen, staan in wat is een breaking change.
Houd één permanente, koppelbare entry per verandering. Een e-mail is geen archief en een Slack-bericht is geen referentie. Kosten van overslaan: niemand kan zes maanden later antwoorden “wanneer is dit veranderd”, jullie zelf ook niet. De e-mail heeft toch een taak, behandeld in de product-update e-mailtemplate; hij wijst naar de entry in plaats van hem te vervangen.
Groepeer op resultaat, niet op systeem. Kosten van overslaan: de lezer moet jullie architectuur in het hoofd houden om te weten welke sectie relevant is. De volgorde die hieruit voortvloeit staat in hoe schrijf je release notes.
Houd de saaie sectie. Dependency-updates en interne wijzigingen blijven, onderaan, elk één regel. Kosten van overslaan: het security-team, wie compliance controleert en wie een versiemismatch debugt verliezen hun enige bron. De entries waar dit het vaakst misgaat zijn de fixes; bugfix release notes laat zien hoe je ze schrijft zodat een lezer weet of hij moet handelen.
Wat zijn de beste practices voor een changelog, en hoe verschillen die?
Een changelog is een naslagwerk, dus zijn practices gaan over volledigheid en structuur in plaats van overtuiging. De vier die ertoe doen:
- Een vast entrytype per regel. Added, Changed, Deprecated, Removed, Fixed, Security. Geen huisstijl, maar een filter: het is wat het mogelijk maakt te vragen om “alleen de breaking changes”. De conventie Keep a Changelog is de gebruikelijke bron.
- Een unreleased-sectie. Waar entries leven tussen merge en release. Het ontbreken ervan is de reden waarom teams entries laat schrijven.
- ISO-datums.
2026-08-28, niet28/08/26, wat twee verschillende dagen betekent afhankelijk van de lezer. - Eén entry per verandering, niet per commit. Drie commits die één bug oplossen zijn één entry.
De twee artefacten worden grondig vergeleken in changelog vs release notes; de korte versie is dat de practices van de changelog volledigheid beschermen en die van de release notes aandacht beschermen. Private release notes voor enterprise-klanten behandelt een versie hiervan die pas opduikt zodra jullie klanten niet meer allemaal op dezelfde build zitten: dezelfde doelen van volledigheid en aandacht, maar afgestemd per account in plaats van naar iedereen tegelijk uitgezonden.
Drie die pure cargocultus zijn
Emoji als entrytypes. Een raket en een moersleutel zijn geen taxonomie. Ze ogen netjes en kunnen niet nuttig worden gefilterd, gesorteerd of door een schermlezer worden gelezen. Gebruik woorden, en als je de emoji wilt, zet hem dan achter het woord.
Semantische versienummers als koppen voor een gehost product. Semver is een belofte over API-compatibiliteit. Voor een SaaS-product waar niemand zijn versie kiest, is een versienummer in de kop interne archivering vermomd als nieuws. Houd semver in de changelog en buiten de aankondiging.
Publiceren volgens een schema ongeacht de inhoud. Maandelijkse notes zonder inhoud leren mensen dat jullie notes ruis zijn. Publiceer wanneer er iets te zeggen is. De changelog dekt de rest.
Degene die echt moeilijk is
De changelog en de aankondiging synchroon houden, zonder alles dubbel te schrijven.
De meeste teams beginnen met één pagina, splitsen die wanneer de doelgroepen uiteenlopen, en laten dan stilletjes een van de twee wegrotten, meestal de changelog, omdat die geen deadline eraan vast heeft. De uitweg is structureel in plaats van disciplinair: houd de entries als data met een type, een datum en een doelgroep, en behandel beide oppervlakken als weergaven daarvan. Ons overzicht changelog-tools dekt wat daarvoor beschikbaar is, inclusief de tools waarmee we concurreren, en de pagina Beamer-alternatief is de eerlijke vergelijking tegenover de widget waarmee de meeste teams beginnen.
De release notes template is waar de selectiestap leeft zodra de entries bestaan.
Als je er maar één invoert
Schrijf de entry op het moment van de merge, in een vast formaat, met een type. Elke andere practice op deze pagina wordt makkelijker zodra die op zijn plek staat, en geen enkele overleeft zonder.
FAQ
Zouden release notes screenshots moeten hebben? Alleen van wat is veranderd, in gebruik. Een screenshot van een instellingenpagina die niemand ooit bezocht voegt scroll toe, geen informatie. Tekst die het resultaat en de getroffen lezer benoemt verslaat een afbeelding die geen van beide toont.
Hoe schrijf je release notes voor een breaking change? Eerst de datum, dan de getroffen aanroepers, dan de vereiste actie, dan de migratie. Begin nooit met het versienummer. De volledige vorm, met een voorbeeldentry, staat in wat is een breaking change.
Zouden release notes door engineering of marketing geschreven moeten worden? Opgesteld door de engineer die de verandering maakte, op het moment van de merge, en geredigeerd door iemand die het als buitenstaander leest. Geen van beide alleen levert notes op waar een klant naar kan handelen.
Wat is het ideale format voor release notes? Eerst de items met een deadline, dan de nieuwe mogelijkheden, dan de verbeteringen, dan een lijst van elk één regel met de rest. De release notes template is dat format als invulpagina.
De technische beweringen in dit artikel zijn niet onafhankelijk gecontroleerd. Klopt er iets niet, laat het ons weten, dan corrigeren we het.