Changelog-voorbeelden

1. Een gewone SaaS-release

Het gebruikelijke geval: een handvol voor de gebruiker zichtbare wijzigingen, geen migratie, geen drama. Het is kort omdat de release klein was, en de drang om het op te vullen weerstaan is het grootste deel van het vak.

## 20 augustus 2026

### Nieuw
- Opgeslagen weergaven in de inbox. Zet een filter één keer vast en
  gebruik het opnieuw vanuit de zijbalk.

### Verbeterd
- De exportjob toont nu voortgang in plaats van vast te lijken bij
  grote accounts.

### Opgelost
- Uitgenodigde leden zien niet langer een leeg dashboard vóór hun
  eerste keer inloggen.

2. Een API-release met een deprecatie

Wie een API-changelog leest, zoekt één ding: of de eigen integratie op het punt staat kapot te gaan, en hoeveel tijd er nog rest. Zet dat bovenaan en geef er een datum bij.

## Acme API 4.2 - 20 augustus 2026

### Belangrijke wijzigingen
- `?page=` wordt verwijderd op alle lijst-endpoints. Gebruik de
  waarde `nextCursor` uit het vorige antwoord.
  `?page=` geeft na 1 oktober 2026 een 400.
  Migratiestappen: acme.example/docs/pagination

### Nieuw
- Webhooks kunnen worden beperkt tot één project.

### Verbeterd
- Lijst-endpoints reageren ongeveer vier keer sneller bij accounts
  met meer dan 10.000 records.

3. Een mobiele release

App stores tonen een afgekapt veld met nieuws, en de review kan een build dagenlang tegenhouden. Beide feiten vormen het item.

## iOS 3.4.0 - 20 augustus 2026

Offline modus. Openen, lezen en opstellen zonder verbinding;
alles synchroniseert zodra je weer online bent.

### Ook in dit release
- Snellere start op oudere apparaten.
- Crash opgelost bij het openen van een gedeelde link vanuit Mail.

4. Een beveiligingsfix

Het enige item waarbij minder zeggen juist is. Gebruikers moeten weten dat ze moeten updaten; niemand anders heeft een beschrijving nodig die precies genoeg is om de nog niet bijgewerkte versie aan te vallen.

## 20 augustus 2026

### Beveiliging
- De validatie van sessietokens is aangescherpt. Accounts op
  zelf gehoste installaties moeten upgraden naar 4.2.1 of later.
  Verantwoord gemeld; geen aanwijzingen voor misbruik.
  Details: acme.example/security/2026-08

5. Hoe een slecht item eruitziet

Elke regel hier heeft een echte vorm, en elke regel is een fout:

## v2.3.7

- PR #482 samengevoegd vanuit feature/inbox-refactor
- Bump van lodash 4.17.20 -> 4.17.21
- Race condition in MembershipCache.resolve() opgelost
- Diverse bugfixes en verbeteringen
- Refactoring van het SavedView-model (dank je, Dave!)

Wat de goede gemeen hebben

• Ze beschrijven een resultaat, geen implementatie. Iemand die de code nooit heeft gezien, kan toch zien of het item hem aangaat.
• Ze laten dingen weg. Dependency-updates, refactors, CI-wijzigingen en interne hernoemingen ontbreken, en juist die afwezigheid houdt de rest leesbaar.
• Ze zetten het kostbare vooraan. Als iets kapot gaat, is dat de eerste kop, met een datum.
• Ze zijn op een bruikbare manier gedateerd: een versienummer waar gebruikers versies zien, een datum waar ze dat niet kunnen.
• Ze zijn expres saai. Geen uitroeptekens, geen marketingbijvoeglijke naamwoorden, geen 'we zijn verheugd aan te kondigen'. Wie een changelog leest, zoekt informatie en ergert zich aan alles wat daarvoor staat.

Veelgestelde vragen

Welk format moet een changelog gebruiken?

keepachangelog.com komt het dichtst bij een standaard, en de sectienamen ervan (Added, Changed, Deprecated, Removed, Fixed, Security) zijn breed erkend. Dat weegt veel minder zwaar dan de formulering binnen de secties. Een consistent format met vage items is erger dan een los format met concrete items.

Hoe vaak moeten we publiceren?

Op het ritme dat bij je releases past, en consistent. Publiceren per release is de eenvoudigste regel. Een maand aan releases samenvoegen in één post maakt elke afzonderlijke wijziging later moeilijker terug te vinden, en dat is precies het moment waarop de meeste mensen een changelog echt lezen.

Moet de changelog op onze eigen site staan of op een pagina van een derde?

Op je eigen site als het kan, want daar komen het verkeer en de zoekwaarde terecht, en omdat een changelog op een domein van iemand anders een link van je product verwijderd is in plaats van er deel van uit te maken. Dat is het argument om het als een feed aan te bieden die je zelf rendert, in plaats van een gehoste pagina waarnaar je linkt.

Lezen mensen changelogs echt?

Een klein deel leest ze regelmatig en een veel groter deel zoekt ze op het moment dat er iets verandert onder hun voeten. Die tweede groep is de reden om het symptoom te schrijven in plaats van de oorzaak: ze zoeken naar wat hen is overkomen, in hun eigen woorden.

Verder lezen: Changelog vs release notes: wat is het verschil? en Keep a Changelog, écht geïmplementeerd.