Changelog: wat is het? Met een voorbeeld

Een changelog is het gedateerde overzicht van wat er veranderde in een product, geschreven voor de mensen die de verandering raakt, niet voor het team dat het uitbracht. Elke regel noemt een verandering, zegt wanneer die inging, en zegt wat de lezer ermee moet doen, wat bij de meeste regels niets is. Dat laatste onderscheidt een changelog van een commit log: een commit log is een overzicht voor wie de code schreef, een changelog is een overzicht voor wie het gebruikt.

Wat is een changelog, precies?

Een lijst met gedateerde regels, nieuwste eerst, elk beschrijft één verandering in termen die de lezer kan controleren. Niet wat het team bouwde, maar wat nu anders is. “Facturatieservice gerefactored” is een commit-bericht. “Facturen tonen nu btw als aparte regel” is een changelog-regel, omdat het de lezer iets vertelt dat ze op hun eigen account kunnen controleren.

Het format is oud en bewust eenvoudig: een kop per release of per dag, een korte lijst eronder, soms een categorie-label. Keep a Changelog is de meest geciteerde specificatie voor deze vorm, en bestaat omdat de meeste projecten die geen specificatie volgen, in plaats daarvan hun commitgeschiedenis dumpen, wat een andere vraag beantwoordt dan waarmee de lezer kwam.

De vijf overlappen in de praktijk, maar zijn niet hetzelfde document, en het verschil zit in wie het vasthoudt op het moment van lezen. Een changelog is degene die gebouwd is om doorzocht en later opnieuw gelinkt te worden, waardoor de regels meer dan de andere behoefte hebben aan vaste datums en stabiele URL’s.

Wat bevat een changelog-regel eigenlijk?

Vier dingen, in deze volgorde: wat er veranderde, geformuleerd in termen die de gebruiker of aanroepende partij zou opmerken; wanneer het inging; tot welke categorie het behoort (added, fixed, changed, removed zijn de vier gangbare); en, wanneer het ertoe doet, wat de lezer ermee moet doen. Een link naar meer detail is welkom. Een alinea interne rechtvaardiging niet, want de lezer vroeg niet naar het waarom, maar naar het wat.

## 2026-09-07

### Added
- Facturen tonen nu btw als aparte regel, in de accountvaluta van de
  klant.

### Fixed
- Een rapport exporteren als CSV liet niet langer de laatste rij vallen
  wanneer het rapport meer dan 10.000 rijen bevatte.

Die vorm schaalt van een update van twee regels tot honderd regels in één release zonder van structuur te veranderen, en dat is de echte test of een format werkt: leest het even goed in een drukke week als in een rustige.

Wie schrijft een changelog, en wanneer?

Wie de verandering doorvoerde, op het moment van uitbrengen, niet een technisch schrijver die het een week later uit tickets reconstrueert. Wie de code aanraakte, weet wat er echt veranderde voor de gebruiker; een achteraf geschreven samenvatting neigt ernaar het ticket te beschrijven in plaats van wat er echt uitkwam, wat meestal breder of smaller is dan de werkelijke omvang. Sommige teams voegen een reviewstap toe voordat een regel publiek wordt, vooral om interne taal op te vangen die is binnengeslopen, en die review moet snel genoeg zijn dat de regel nog dezelfde dag verschijnt.

Waar hoort een changelog te staan?

Op een eigen pagina, op een stabiele URL, verspreid als feed. Verstopt in een instellingenmenu of een release-tag op een codehost, bereikt het alleen wie al wist waar te kijken. Een publieke pagina kan gelinkt worden vanuit een supportticket, geciteerd in een review, of geabonneerd. De feed telt net zo zwaar als de pagina: een lezer die eens per maand de changelog van een product checkt is zeldzaam, een die zich erop abonneert niet, en alleen de feed bedient de tweede groep.

Hoe verschilt het van release notes?

De twee worden constant door elkaar gehaald, en verschillen genoeg dat ze samenvoegen een document oplevert dat geen van beide lezers goed dient. Changelog vs release notes behandelt het onderscheid volledig; kort gezegd is een changelog het volledige, chronologische overzicht, en release notes zijn een gecureerde selectie, geschreven om een update de moeite waard te laten klinken. Een product heeft meestal beide nodig, gericht op verschillende momenten in de dag van de lezer.

Wat maakt een changelog het lezen waard?

Specificiteit en eerlijkheid over de eigen reikwijdte. “Diverse bugfixes” is de zin die een lezer leert om de pagina niet meer te openen, omdat die niets belooft dat te controleren valt. Een regel die het exacte gedrag noemt dat veranderde, zelfs bij een kleine fix, is degene die een abonnement levend houdt. Die discipline geldt ook voor wat wordt weggelaten: een changelog die alleen successen aankondigt en nooit een fix voor iets dat kapot was, leest als marketing verkleed als changelog, en lezers merken dat.

Versioneringsdiscipline telt ook. Semantic versioning en je changelog laat zien hoe versienummer en regel moeten overeenkomen, zodat een lezer die de versiegeschiedenis doorloopt hetzelfde signaal twee keer krijgt in plaats van twee verschillende.

Hoe worden changelogs gegenereerd?

Op twee manieren, en de meeste echte opzetten zijn een mix. Geautomatiseerde generatie leest commit-berichten, meestal in Conventional Commits-formaat, en zet die om in regels zonder dat iemand de output aanraakt; van conventional commits naar changelog behandelt die pipeline. Gecureerde generatie betekent dat iemand elke regel met de hand schrijft of bewerkt. Geautomatiseerde output is sneller en mist nooit een gemergde pull request, maar erft elk vaag commit-bericht letterlijk over, dus de meeste teams die automatiseren houden toch een lichte redactieslag aan voor publicatie in plaats van de ruwe output te tonen.

FAQ

Heeft elk product een changelog nodig? Elk product met gebruikers die geraakt worden door verandering heeft er een nodig, of het nu een SaaS-app, een intern tool, of een publieke API is. De vorm past zich aan (een API-changelog leest anders dan die van een consumentenapp), de behoefte niet.

Wat is een changelog in softwaretermen? Dezelfde definitie als hierboven: een gedateerde, chronologische lijst van wat er veranderde in de software, geschreven voor wie het gebruikt, niet voor wie het bouwde.

Kan een changelog automatisch gegenereerd worden uit commits? Ja, en veel teams doen precies dat, meestal vanuit Conventional Commits-berichten. Het nadeel is dat een gegenereerde regel maar zo duidelijk is als het commit-bericht waar hij vandaan komt, dus een reviewslag voor publicatie vangt de regels die herschreven moeten worden.

Is een changelog hetzelfde als een versiegeschiedenis? Dicht genoeg bij elkaar dat de termen door elkaar gebruikt worden. Een versiegeschiedenis is soms alleen een lijst van versienummers en datums zonder beschrijving; een changelog bevat altijd wat er veranderde.

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: Changelog-voorbeelden, Documentatie voor ontwikkelaars