Software release notes: wat ze zijn en wat erin hoort

Software release notes zijn het document dat bij een versie van software hoort en de lezer vertelt wat er in die versie veranderde, wie de wijziging raakt en wat hij, als dat al nodig is, moet doen. Ze worden één keer per release geschreven en gelezen door mensen die willen weten of ze moeten upgraden, mensen die nagaan of hun probleem is opgelost en mensen die het product ondersteunen. Goede notes zijn kort, specifiek voor de versie en eerlijk over alles wat breekt.

Wat zijn software release notes?

Het is een gedateerde, geversioneerde samenvatting van één release. Een release note beantwoordt drie vragen voor een lezer die er niet bij was: wat is anders, raakt het mij en moet ik iets doen. De volledige geschiedenis van het project is de changelog, en het commitlog is voor degenen die de code schreven.

Dezelfde feiten kunnen in een changelog-entry en in release notes staan. Het verschil zit in selectie en doelgroep: de changelog noemt elke relevante wijziging, terwijl release notes beginnen met wat een lezer zal opmerken en dat uitleggen. Changelog vs release notes trekt die lijn in detail.

Wat hoort er in software release notes?

Neem de versie en datum op, een samenvatting van één alinea, en daarna de wijzigingen gegroepeerd naar wat de lezer ermee kan. Zeg bij elke wijziging wat er anders is in de termen van de lezer, wie erdoor geraakt wordt en of actie nodig is.

Een complete set bestaat uit deze onderdelen:

1. Versienummer en releasedatum. Gebruik het format van je tags, zodat een lezer de notes aan een build kan koppelen.
2. Een samenvatting. Twee of drie zinnen: waar deze release voor dient en of upgraden iets van de lezer vraagt.
3. Nieuwe features en verbeteringen. Wat de lezer nu kan, niet wat de code nu bevat.
4. Fixes. Het symptoom dat verdween en de versie waarin het begon.
5. Breaking changes en deprecaties. Wat niet meer werkt, wanneer, en wat je in plaats daarvan gebruikt. Zet die vooraan als ze er zijn.
6. Bekende problemen. Alles wat je hebt uitgebracht en waarvan je weet dat het niet klopt, met een workaround als die er is.
7. Eisen en upgradestappen. Ondersteunde platforms, minimumversies, migratiecommando’s.

Laat refactors, dependency-bumps zonder zichtbaar effect en interne tickets weg. Als een lezer de wijziging niet kan merken, hoort ze in de git-geschiedenis. Hoe schrijf je release notes behandelt formulering en volgorde.

Hoe ziet een software release note eruit?

Hier is een korte voor een verzonnen command-line tool. De vorm doet er meer toe dan de inhoud.

## 2.4.0 (2026-10-08)

Faster exports and one breaking change to the config file. Upgrade
needs a one-line edit to `tool.yml`.

### Breaking
- `output:` in `tool.yml` is now `export.path:`. Old configs fail
  with "unknown key". Rename the key; nothing else changes.

### New
- Exports stream to disk, so files over 100 MB no longer time out.

### Fixed
- Search works again for queries containing a hyphen. Broken
  since 2.3.0.

### Known issues
- Windows paths longer than 260 characters still fail. Use a
  shorter output directory for now.

De breaking change staat vooraan, met de exacte fouttekst die een lezer zal zien, omdat mensen op foutmeldingen zoeken. De fix noemt de versie waarin het brak, zodat een lezer kan zien wanneer zijn probleem begon. Het bekende probleem heeft een workaround, en dat is beter dan zwijgen. Release notes voorbeelden bevat meer formuleringen voor elk type entry.

Hoe verschillen software release notes per doelgroep?

Houd één bron van waarheid en schrijf per doelgroep een versie. De feiten veranderen niet, het detailniveau wel. Klanten willen het voordeel in één regel, beheerders willen eisen en bekende problemen, developers willen exacte namen en versies, en support wil weten wat te zeggen als er een ticket binnenkomt.

Bij API-producten vraagt de versie voor developers de meeste zorg, want een kleine fix voor jou kan voor een aanroeper een storing zijn. API changelog en breaking changes behandelen die doelgroep. Voor de interne versie beschrijft interne release notes wat support en sales nodig hebben en klanten niet.

Waar publiceer je software release notes?

Publiceer ze waar de lezer al is op het moment dat hij de vraag stelt. Bij een mobiele app is dat de storepagina, waar het platform per versie een veld voor release notes biedt; Apple beschrijft hoe je release notes voor builds opgeeft. Bij een webproduct is het een changelog-pagina met een link vanuit de app. Bij een library is het de releasepagina plus een bestand in de repository, zoals beschreven in GitHub release notes.

Houd elke versie op een vaste URL zodat support ernaar kan linken, en bewaar oude versies. Een lezer op versie 2.2 heeft ook de notes van 2.3 en 2.4 nodig. Voor een startstructuur geeft de release notes template je koppen om te kopiëren.

Hoe lang moeten release notes zijn?

Zo lang als de wijziging vraagt en niet langer. Een patchrelease kan drie regels zijn. Een major release met een migratie heeft een pagina nodig, en waarschijnlijk een aparte migratiegids waarnaar de notes verwijzen. De test is of een lezer die alleen het eerste scherm scant weet of de release hem raakt. Zo niet, zet de samenvatting hoger en schrap de rest. Beste practices voor release notes somt op wat standhoudt en wat gewoonte is.

FAQ

Wat zijn software release notes? Ze zijn een geversioneerde samenvatting van wat er in één release van een stuk software veranderde, geschreven voor de mensen die het gebruiken of ondersteunen. Ze behandelen nieuwe features, fixes, breaking changes en alles wat de lezer moet doen.

Wat is het verschil tussen release notes en een changelog? Een changelog is het volledige doorlopende register van relevante wijzigingen. Release notes zijn een bericht over één release, geselecteerd en herschreven voor lezers die beslissen of ze upgraden. Veel teams publiceren de changelog-entry van een versie als release notes.

Wie schrijft software release notes? Meestal de productmanager, een technisch schrijver of de engineer die de wijziging uitbracht, met iemand die de toon nakijkt. De beste resultaten ontstaan wanneer degene die het dichtst bij de wijziging staat het concept schrijft en een tweede persoon het voor de lezer redigeert.

Hebben kleine releases release notes nodig? Ja, korte. Zelfs een patchrelease moet zeggen wat er is gefixt en of de lezer iets moet doen. Een note van één regel is beter dan geen, want “bugfixes en verbeteringen” vertelt de lezer niets.

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, Changelog-voorbeelden