changeloop blog

Bugfix release notes schrijven die mensen gebruiken

Fri, 02 Oct 2026 00:00:00 GMT

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.

Voor (het commitbericht)	Na (het symptoom)
Null pointer in export handler opgelost	Exports falen niet meer met "Er ging iets mis" als een project geen tags heeft. Draai elke export die sinds 3 september faalde opnieuw.
Race condition in sync-worker opgelost	Bewerkingen op twee apparaten binnen een paar seconden overschrijven elkaar niet meer. Niets te doen.
Tijdzonebug gefixt	Geplande rapporten draaien nu op het tijdstip dat je instelde. Accounts ten oosten van UTC zagen rapporten sinds 12 augustus tot een dag te vroeg. Geen wijziging nodig.
XSS in comment renderer gepatcht	Beveiligingsfix: een speciaal opgemaakte reactie kon een script uitvoeren in de browser van een andere gebruiker. Upgrade vandaag naar 4.2.1. In onze logs zagen we geen misbruik.
Regressie uit 4.1.0 opgelost	Zoeken werkt weer voor zoekopdrachten met een koppelteken. Het brak in 4.1.0 en is opgelost in 4.1.1.
Bugfixes en prestatieverbeteringen	Zeg welke. Zie de laatste sectie.

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:

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.
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.
Het venster. Sinds welke release of datum, zodat een lezer kan beslissen of het vreemde resultaat van gisteren de bug was.
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.

Krijgt een eigen entry	Hoort in de lijst met kleine fixes
Gemeld door een klant of door velen geraakt	Cosmetisch mankement op een zelden geopend scherm
Veroorzaakte verkeerde uitvoer, mislukte taken of verloren werk	Typfout, witruimte, een scheef icoon
Vraagt een actie van de lezer	Fix in een intern tool of adminpagina
Een regressie uit een recente release	Fout die alleen in een testomgeving optrad
Raakt facturatie, rechten of data	Logformulering, dependency-bumps zonder effect voor gebruikers

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.

Klantfeedback vragen in een softwareproduct

Fri, 02 Oct 2026 00:00:00 GMT

Om klantfeedback te vragen in een softwareproduct stel je één concrete vraag over iets wat de gebruiker net deed, op de plek waar hij het deed. "Hoe ging het exporteren van dat rapport?" direct na een export levert een antwoord op. "Vertel ons wat je van ons product vindt" in een footer levert stilte op. De rest van deze pagina bestaat uit de momenten, de kanalen en de exacte formuleringen.

Het meeste advies over dit onderwerp is geschreven voor winkels en servicedesks. Een softwareteam weet precies wat de gebruiker een seconde geleden deed, dus de vraag kan daarover gaan.

Moment	Waar vragen	Kant-en-klare vraag
Direct nadat een taak klaar is	In de app, naast het resultaat	"Deed die export wat je nodig had?"
Na het eerste gebruik van een nieuwe feature	In de app, één keer	"Wat probeerde je te doen met Bulk Edit?"
Nadat een supportticket is opgelost	In de supportthread	"Heeft dat het opgelost, of klopt er nog iets niet?"
Nadat een gebruiker vastloopt of een flow verlaat	E-mail, een dag later	"Je stopte bij stap 3 van de setup. Wat zat in de weg?"
Na 30 dagen regelmatig gebruik	E-mail van een persoon met naam	"Wat is het ene wat je zou veranderen?"
Wanneer een gebruiker opzegt	In de opzegflow	"Waarom besloot je vandaag te vertrekken?"
Nadat je iets uitbrengt waar ze om vroegen	Waar ze erom vroegen	"Je vroeg om CSV-import. Het is live. Dekt het jouw situatie?"

Wat is het juiste moment om feedback te vragen?

Het juiste moment is direct nadat de gebruiker iets heeft afgerond, terwijl de details nog in zijn hoofd zitten. Een vraag die op een actie volgt, krijgt een antwoord over die actie. Een vraag die uit het niets komt, krijgt een antwoord over de stemming van de persoon, of geen antwoord.

Vraag niet bij de aanmelding, want niemand heeft nog iets gebruikt. Vraag niet midden in een taak, want dan onderbreek je precies wat je wilt leren kennen. Laat iemand die heeft geantwoord met rust tot je iets te melden hebt.

Waar vraag je klantfeedback het best?

Vraag op de plek waar de ervaring plaatsvond. Een prompt in de app past bij een vraag over een scherm. De supportthread past bij een vraag over een oplossing. E-mail past bij een vraag over een week gebruik, of over een flow die iemand afbrak. Een gesprek past bij de vragen die je niet kunt voorspellen.

Elk kanaal levert een ander soort antwoord op:

In de app: kort, direct en concreet, maar alleen van mensen die er op dat moment zijn. Van gebruikers die al weg zijn hoor je niets.
Supportthread: van mensen die al gefrustreerd genoeg waren om te schrijven. Goed om kapotte dingen te vinden, slecht om de rest van het product te beoordelen.
E-mail: langere antwoorden van minder mensen, en de enige manier om gebruikers te bereiken die stil zijn geworden. Schrijf het als een korte notitie van een persoon met naam, met één vraag erin.
Interview: de manier om te leren waarom mensen dingen doen. Vraag ze te laten zien hoe ze werken, en zwijg terwijl ze dat doen.

Kwaliteit van feedbacksignalen behandelt hoe je weegt wat elk kanaal je vertelt.

Hoe vraag je op een professionele manier om feedback?

Wees specifiek over het onderwerp, zeg waarom je het vraagt en zorg dat het antwoord minder dan een minuut kost. Een professionele vraag noemt het moment, maakt duidelijk dat een mens het antwoord leest en verontschuldigt zich niet voor de onderbreking.

Noem de exacte actie ("de export die je zojuist draaide"), vraag om één ding, gebruik een vrij tekstveld zonder verplichte velden en onderteken met een voornaam.

Wat is een goede zin om feedback te vragen?

Een goede zin is een vraag over een specifiek moment die in een paar woorden te beantwoorden is. Vergelijk de twee kolommen hieronder. De linkse kun je met een schouderophalen beantwoorden. De rechtse vragen de persoon iets echts te herinneren.

Zwakke vraag	Sterkere vraag
"Nog feedback?"	"Wat was het lastigste bij het instellen hiervan?"
"Wat vind je van ons product?"	"Waarvoor gebruikte je dit vorige week?"
"Beoordeel je ervaring van 1 tot 10."	"Heb je vandaag gedaan wat je kwam doen?"
"Vertel ons hoe we kunnen verbeteren."	"Wat is één ding dat je deze week ophield?"
"Zou je ons aanbevelen?"	"Aan wie liet je dit laatst zien, en wat zei je?"

Nog een vraag die bijna overal werkt: "Wat gebruik je in plaats daarvan als dit voor jou niet werkt?" Die brengt de echte concurrent naar boven, en dat is vaak een spreadsheet.

Wat zijn de slechtste manieren om feedback te vragen?

De slechtste vragen zijn breed, vroeg, lang of sturend. Ze hebben één probleem gemeen: de persoon kan niet antwoorden zonder het denkwerk te doen dat jij had moeten doen.

"Vul onze enquête van 20 vragen in." De mensen die hem afmaken hebben de meeste vrije tijd of de sterkste mening.
Een popup op de eerste pagina na het inloggen. De gebruiker kwam iets doen en jij blokkeerde het. Wegklikken is het enige verstandige antwoord.
"We horen graag je feedback!" zonder vraag. Het vraagt de gebruiker het onderwerp te verzinnen.
Een sturende vraag: "Hoe dol ben je op het nieuwe dashboard?" Je krijgt instemming en leert niets.
Een score zonder vervolgvraag. Een 6 uit 10 vertelt je de stemming. Het vertelt je niet wat je moet veranderen.
Vragen, en dan zwijgen. Dat kost je de volgende ronde, zoals hieronder staat.

Hoe noem je klantfeedback over een product?

Feedback over een product heet meestal productfeedback, en die valt in twee soorten uiteen. Een bugmelding zegt dat iets niet werkt zoals bedoeld. Een featureverzoek zegt dat iets ontbreekt. Het onderscheid bepaalt wie het eerst bekijkt, en featureverzoek of bug trekt die lijn. Een derde soort, lof, is het bewaren waard en het citeren met toestemming.

Een feedbackformulier dat "Bug" en "Featureverzoek" als eerste keuze aanbiedt, doet die eerste sortering voor je.

Wat doe je met de antwoorden?

Zet elk antwoord waar het team al werkt, met de woorden van de persoon intact. Een enkele geciteerde regel is beter dan jouw samenvatting ervan. Tag het op type en grove urgentie, voeg herhalingen samen en beslis: bouwen, parkeren of afwijzen.

Afwijzen telt ook als antwoord. "We gaan dit niet bouwen, en dit is waarom" maakt een einde aan het wachten, en featureverzoeken afwijzen heeft formuleringen daarvoor. Voor de leidingen beschrijft featureverzoeken bijhouden hoe je verzoeken uit vijf kanalen in één lijst krijgt. Als je verzoeken schriftelijk aanneemt, houdt een feature request template ze vergelijkbaar.

De widget van Changeloop maakt van elke inzending een GitHub-issue, zodat feedback landt naast de code die het gaat oplossen. Met elk tool is de regel hetzelfde: één lijst, één eigenaar, geen antwoord dat in iemands inbox blijft liggen.

Waarom vertel je wat er live ging?

Het laat de persoon zien dat antwoorden de moeite waard was. Een gebruiker die je iets vertelde en later hoort "dit is uitgebracht, bedankt" heeft een reden om weer te antwoorden. Wie niets hoort, concludeert dat het vakje niet wordt gelezen.

De laatste stap van het vragen is dus een antwoord. Vertel elke persoon die erom vroeg wanneer zijn verzoek live gaat, in zijn eigen termen, op het kanaal dat hij gebruikte. De feedback-loop met klanten sluiten beschrijft het mechanisme: de gepubliceerde changelog-entry is wat het bericht activeert, zodat de aanvrager pas wordt ingelicht als de wijziging live is. Als in Changeloop widgetfeedback een GitHub-issue werd en de gemergede pull request die sluit, plaatst het goedkeuren van de entry een "Shipped"-reactie op die issue en toont het de entry aan de indiener in de widget; handmatig aangemaakte issues en GitLab- of Bitbucket-repositories krijgen geen reactie. Onze docs beschrijven de setup van widget en feed.

Een antwoord kan kort zijn: "Je vroeg in maart om CSV-import. Het is vandaag live, en zo werkt het." Het geeft je ook de beste volgende vraag, namelijk of het dekt wat ze nodig hadden.

Een beginplan

Kies één moment uit de tabel bovenaan, het moment waarop gebruikers het vaakst slagen of afhaken. Schrijf er één vraag voor, zet hem in één kanaal en lees twee weken lang elk antwoord voordat je een tweede prompt toevoegt. Antwoord iedereen die je iets concreets gaf.

FAQ

Hoe vaak moet je klanten om feedback vragen? Koppel vragen aan gebeurtenissen, niet aan een kalender. Een gebruiker mag hoogstens één prompt per week zien, en geen direct na het beantwoorden van een andere. Het eerste bericht na feedback moet een antwoord zijn over wat ermee gebeurde.

Hoe vraag je feedback zonder gebruikers te irriteren? Vraag na een taak, nooit midden in een taak, houd het bij één vraag en maak wegklikken makkelijk. Respecteer een afwijzing een paar weken.

Moet je een beloning voor feedback aanbieden? Meestal is dat niet nodig. Een concrete vraag en een zichtbaar antwoord wegen zwaarder dan een cadeaubon, en beloningen trekken mensen aan die de beloning willen. Bewaar ze voor interviews, waar je om 20 minuten van iemands tijd vraagt.

Wat als niemand antwoordt? Maak de vraag smaller en breng hem dichter bij het moment, bijvoorbeeld één scherm, gevraagd direct nadat het is gebruikt. Blijft het stil, mail dan een handvol gebruikers rechtstreeks en gebruik die gesprekken om betere prompts te schrijven.

Product roadmap voorbeelden: zes formats en hun valkuilen

Fri, 02 Oct 2026 00:00:00 GMT

De product roadmap voorbeelden die het kopiëren waard zijn vallen in zes formats: Now/Next/Later, een kwartaaltijdlijn, een themaroadmap, een uitkomstroadmap, een publieke roadmap en een interne releaseroadmap. Elk beantwoordt een andere vraag voor een andere lezer, dus het juiste voorbeeld is het voorbeeld dat past bij wie jouw roadmap gaat lezen. De lay-out beslis je als laatste.

Elk voorbeeld hieronder hoort bij een verzonnen product, een kleine taken-app voor teams, en elk item is verzonnen. Het gaat om de vorm: wat er in elk vak komt, hoe een echte entry eruitziet en waardoor dat format na een kwartaal uit elkaar valt.

Wat zijn goede voorbeelden van een product roadmap?

Een goed roadmapvoorbeeld is kort, noemt een lezer en doet één soort belofte. Kies het format op basis van de belofte die je wilt waarmaken: een richting, een datum, een thema van werk, een resultaat, een publieke toezegging of een leveringsschema.

Format	Gemaakt voor	Werkt wanneer	Faalt wanneer
Now/Next/Later	Het hele bedrijf	Plannen vaak veranderen	"Next" volloopt en een wachtrij wordt
Kwartaaltijdlijn	Sales, support, directie	Datums echte randvoorwaarden zijn	Datums opschuiven en niemand ze bijwerkt
Thema's	Leiderschap, nieuwe collega's	Je het waarom wilt uitleggen	Thema's zo breed worden dat alles past
Uitkomsten	Product en engineering	Je het doel kunt meten	De metric geen eigenaar of data heeft
Publiek	Klanten	Je hem klein kunt houden	Hij een dumpplaats voor de backlog wordt
Interne release	Engineering, QA, support	Meerdere teams samen opleveren	Hij voor strategie wordt aangezien

Hoe ziet elk product roadmap voorbeeld eruit?

Elk format hieronder staat met realistische entries, gevolgd door voor wie het past, wanneer het standhoudt en waar het meestal misgaat.

Now/Next/Later

NOW (deze maand in ontwikkeling)
  Opgeslagen weergaven in de inbox
  CSV-export die werkt voor grote accounts
NEXT (besloten, volgorde nog niet vast)
  SSO voor het Team-plan
  Slack-meldingen
LATER (een richting, geen toezegging)
  Mobiele app
  Auditlog

Dit past bij een bedrijf dat geen datums wil beloven, wat bij veel vroege teams past. Het houdt stand omdat de drie kolommen beschrijven hoe zeker je bent: "now" is bezig, "next" is besloten, "later" is een hoop. Het faalt wanneer "later" de parkeerplaats wordt voor elk idee dat niemand wil afwijzen, en wanneer "next" ongemerkt een volgorde en een datum krijgt zonder dat iemand het een tijdlijn noemt.

Tijdlijn of kwartaalroadmap

Q4 2026
  Okt   Opgeslagen weergaven in de inbox
  Nov   SSO-bèta met vijf designpartners
  Dec   SSO algemeen beschikbaar
Q1 2027
  Jan   Slack-meldingen
  Mrt   Auditlog (alleen export)

Dit past bij sales, support en finance, die ergens omheen moeten plannen. Het werkt wanneer datums echte randvoorwaarden zijn, zoals een contract, een conferentie of een compliance-deadline. Het faalt wanneer datums gokken zijn, want een maand op een roadmap wordt binnen enkele weken een belofte in een salesdeck. Gebruik je dit format, label dan elk kwartaal als toegezegd of verwacht, en maak het tweede kwartaal zichtbaar vager dan het eerste.

Themaroadmap

THEMA: Eerste week
  Import uit CSV en Trello
  Startsjablonen
THEMA: Klaar voor grotere teams
  SSO
  Auditlog
  Rolrechten
THEMA: Minder handwerk
  Slack-meldingen
  Terugkerende taken

Dit past bij updates voor het management en bij nieuwe collega's, omdat het uitlegt waarom het werk bestaat voordat het het werk opsomt. Het houdt stand wanneer elk thema overeenkomt met een reden waarom een klant het zou willen. Het faalt wanneer de thema's zo breed zijn ("Groei", "Kwaliteit") dat elk item onder elk thema past, waarna de groepering niets meer uitlegt.

Uitkomstroadmap

DOEL: Meer nieuwe teams ronden de setup af
  Metric: setup af binnen 7 dagen, 40% naar 55%
  Weddenschappen: CSV-import, startsjablonen
DOEL: Minder supporttickets over exports
  Metric: exporttickets per week, 30 naar 10
  Weddenschappen: fix voor grote accounts, exportstatuspagina

De cijfers zijn ter illustratie, en het gaat om de opzet: een doel, één metric met een begin- en streefwaarde, en de weddenschappen die je gaat proberen. Het past bij product- en engineeringteams die vertrouwd worden om de oplossing te kiezen. Het werkt wanneer de metric bestaat en iemand hem beheert. Het faalt wanneer het doel niet meetbaar is, of wanneer de "weddenschappen" dezelfde featurelijst als eerst zijn met een uitkomstzin erbovenop geplakt.

Publieke roadmap voor klanten

GEPLAND
  Opgeslagen weergaven in de inbox
IN ONTWIKKELING
  Slack-meldingen
UITGEBRACHT
  CSV-export voor grote accounts

Dit is het kleinste format, en het doet de sterkste belofte. Het past bij klanten, die willen weten of hun verzoek is gehoord. Het houdt stand met heel weinig items, zonder datums en met titels in de woorden van de klant. Het faalt als dumpplaats voor de backlog: elke "misschien" die je noemt is een belofte waar iemand later naar zal vragen. De werking vanuit je issue tracker staat in een publieke roadmap in drie kolommen, dus die herhalen we hier niet.

Interne releaseroadmap

Release	Doel	Eigenaar	Hangt af van	Status
5.2	14 okt	Platform	Upgrade auth-service	Code compleet
5.3	11 nov	Inbox	API voor opgeslagen weergaven	In uitvoering
5.4	9 dec	Platform	Contract met SSO-leverancier	Geblokkeerd

Dit past bij engineering, QA en support, die moeten weten wat samen wordt opgeleverd en wat wat blokkeert. Het werkt wanneer het op de week nauwkeurig is en elke rij een eigenaar heeft. Het faalt wanneer iemand het voor strategie aanziet: een leveringsschema zegt wat het gebouw verlaat en wanneer, en zegt niets over de vraag of die releases de juiste keuzes waren.

Welk product roadmap format moet je kiezen?

Kies eerst op lezer, daarna op hoeveel zekerheid je echt hebt. Als je niet kunt zeggen wie de roadmap leest en welke beslissing hij helpt nemen, redt geen van de voorbeelden hierboven hem.

Klanten die vragen "hebben jullie me gehoord?" Gebruik het publieke format en houd het bij een handvol items.
Sales en support die vragen "kan ik de klant een datum geven?" Gebruik de kwartaaltijdlijn, met toegezegd en verwacht duidelijk gescheiden.
Leiderschap dat vraagt "waarom dit werk?" Gebruik thema's, of uitkomsten als je de data hebt.
Een team dat elke maand van richting verandert. Gebruik Now/Next/Later en weersta de neiging om het te dateren.
Engineers die vragen "wat gaat wanneer live?" Gebruik de releaseroadmap en houd hem los van de strategische.

De meeste teams eindigen met twee: een strategische roadmap in een van de eerste vier vormen, en daaronder een releaseschema. Een publieke roadmap is dan een gefilterde weergave van de strategische, met alleen wat je bereid bent waar te maken.

Hoe schrijf je een product roadmap?

Schrijf een roadmap door de lezer te benoemen, het format te kiezen dat bij zijn vraag past, alleen items op te nemen die je in een vergadering zou verdedigen, en elk item een status en een eigenaar te geven. Bepaal daarna hoe vaak hij wordt beoordeeld voordat je hem publiceert.

Benoem de lezer en de beslissing. "Support beslist wat klanten over SSO te horen krijgen" is een reden. "Iedereen moet de roadmap zien" geeft je niets om voor te ontwerpen.
Begin bij wat je al weet. Openstaande verzoeken, gerangschikt volgens een regel die je kunt uitleggen, zijn betere grondstof dan een brainstorm.
Schrijf elk item als een klantuitkomst. "Bewaar een filter dat je vaak gebruikt" leest beter dan "Persistentie van opgeslagen weergaven implementeren", en het vertelt de klant of het zijn probleem is.
Bepaal wat de roadmap niet bevat. Datums, schattingen en een ideeënbacklog zijn de drie gebruikelijke uitsluitingen.
Zet een beoordelingsdatum. Een roadmap zonder geplande beoordeling heeft een ongeplande begrafenis.

Hoe houd je een product roadmap actueel?

Houd een roadmap actueel door items te verplaatsen wanneer het werk beweegt, vanuit dezelfde plek waar het werk wordt bijgehouden, en door vast te leggen wat er gebeurde toen een item werd uitgebracht of geschrapt. Een roadmap die iemand met de hand bijwerkt in een apart tool raakt verouderd, omdat het niemands dagelijkse werk is.

De goedkoopste bron van waarheid is de issue tracker. Als elke roadmapkolom overeenkomt met een label op de issue, verandert de roadmap wanneer het label verandert en wordt niets overgetypt. De variant van Changeloop gebruikt de labels roadmap:planned, roadmap:building en roadmap:shipped, en als een issue er twee draagt, wint de verst gevorderde. Een kaart naar uitgebracht verplaatsen is nog steeds een eigen labelwijziging, dus maak het onderdeel van de review waarin je de changelog-entry goedkeurt.

Die entry is de andere helft. Wanneer een item wordt uitgebracht, zegt de changelog wat er veranderde in de termen van de klant, en kan een aanvrager die erom vroeg worden ingelicht. Die loop sluiten is het doel van de feedback-loop met klanten, en de roadmap is het stuk van die loop dat de klant ziet voordat er iets wordt uitgebracht. Laat je een item vallen, zeg dat dan; een publiek "nee" sluit ook dat verzoek, en featureverzoeken afwijzen beschrijft hoe je dat verwoordt. Teams die willen zien hoe afgeronde entries lezen, kunnen changelog-voorbeelden bekijken.

FAQ

Wat is het eenvoudigste product roadmap format? Now/Next/Later. Het heeft drie kolommen, heeft geen datums nodig en groepeert items op zekerheid. Voor een klein team dat vaak van richting verandert, is het ook het format waarin je het moeilijkst gênant de mist ingaat.

Hoeveel items moet een product roadmap hebben? Minder dan je denkt. Minder dan tien over alle kolommen is genoeg voor een publieke roadmap, en een interne strategische heeft zelden meer dan een dozijn nodig. Daarboven is het een backlog met een mooiere kop.

Moet een product roadmap datums bevatten? Alleen als de datums echte randvoorwaarden zijn, en dan alleen voor het eerstvolgende kwartaal. Gebruik daarbuiten kolommen of thema's. Een datum op een roadmap wordt in een verkoopgesprek een toezegging, of je dat nu bedoelde of niet.

Wat is het verschil tussen een product roadmap en een releaseplan? Een roadmap zegt wat je van plan bent te bouwen en waarom. Een releaseplan zegt welke build op welke datum live gaat en wie eigenaar is. De roadmap verandert wanneer je strategie verandert, en het releaseplan wanneer het werk verandert.

Releasemanagementproces voor teams die vaak uitbrengen

Fri, 02 Oct 2026 00:00:00 GMT

Een releasemanagementproces is de reeks stappen die een wijziging van "gemerged" naar "draait in productie en is uitgelegd aan de mensen die het raakt" brengt. Voor een team dat vaak uitbrengt komt het neer op zeven stappen: de scope plannen, de wijziging isoleren, bouwen en testen, goedkeuren, deployen en verifiëren, communiceren en terugblikken. Elke stap heeft één benoemde eigenaar en één exitcriterium nodig, anders stopt hij stilletjes.

Deze gids gaat uit van een team van 5 tot 50 engineers dat wekelijks of dagelijks deployt en wil dat het proces uit de weg blijft.

Stap	Eigenaar	Exitcriteria
1. De scope plannen	Product- of techlead	De lijst met wijzigingen in deze release is opgeschreven en alles wat riskant is, is gemarkeerd
2. Branch of flag	De engineer die de wijziging bezit	Werk staat op een kortlevende branch of achter een flag, zodat main uitbrengbaar blijft
3. Bouwen en testen	CI, met de auteur oproepbaar bij fouten	Pipeline groen op exact de commit die live gaat
4. Goedkeuren	Reviewer, plus releasemanager bij riskante wijzigingen	Review klaar, rollbackpad benoemd, go of no-go vastgelegd
5. Deployen en verifiëren	Releasemanager of on-call engineer	Gedeployd, smoke checks slagen, foutpercentage en latency komen overeen met de baseline van voor de release
6. Communiceren	Wie de wijziging begrijpt, geredigeerd door iemand die dat niet doet	Release notes gepubliceerd waar gebruikers lezen, support en sales geïnformeerd
7. Terugblikken	Releasemanager	Metrics gelezen, alles wat misging heeft een eigenaar en een fix

Wat is het releasemanagementproces?

Het is het herhaalbare pad dat een wijziging volgt om gebruikers te bereiken: scope, bouwen, testen, goedkeuren, deployen, verifiëren, aankondigen en terugkijken. Het nut van opschrijven is dat elke release hetzelfde pad volgt, zodat iemand op vakantie, een nieuwe collega of een on-call engineer om 2 uur 's nachts het kan draaien zonder iemand te vragen hoe het werkt.

Wat zijn de verschillende soorten releasemanagement?

Er zijn drie praktische soorten: continuous deployment, geplande releases en gereguleerd change management. Ze verschillen in hoeveel er vóór een release gebeurt en hoeveel is geautomatiseerd. Continuous deployment brengt elke gemergede wijziging uit, geplande releases bundelen wijzigingen in een trein, en gereguleerd change management voegt formele goedkeuring en een audittrail toe.

	Continuous deployment	Geplande releases	Gereguleerd of ITIL-change management
Releaseeenheid	Eén gemergede pull request	Een batch, wekelijks of tweewekelijks	Een wijzigingsverzoek
Scopestap	Impliciet, de merge is de scope	Releaseplanningsoverleg	Wijzigingsrecord met risicoscore
Goedkeuring	Codereview plus geautomatiseerde checks	Releasemanager keurt de batch goed	Change advisory board of gedelegeerde goedkeurder
Risicobeheersing	Feature flags, canaries, snelle rollback	Staging-soak, release candidate	Gedocumenteerd backoutplan, onderhoudsvenster
Gebruikelijke frequentie	Vele per dag	Wekelijks tot maandelijks	Bepaald door de wijzigingskalender
Zwak punt	Niemand vertelt gebruikers wat er veranderde	Grote batches verbergen de wijziging die iets brak	Procestijd overstijgt de wijziging zelf

De meeste teams zijn een mix. Een SaaS-product deployt misschien continu terwijl de mobiele app op een wekelijkse trein gaat, en de ene betalingsservice waar auditors om geven een formeel wijzigingsrecord volgt. Kies het soort per service, niet per bedrijf. Waar wijzigingen maar geleidelijk zichtbaar worden, zijn de release en de aankondiging aparte gebeurtenissen, het geval dat wordt behandeld in release notes bij feature flags.

Wat zijn de verantwoordelijkheden van een releasemanager?

Een releasemanager bezit het pad dat een wijziging naar productie volgt. Hij houdt de releasekalender bij, beslist of een wijziging klaar is, draait of superviseert de deploy, neemt het rollbackbesluit, zorgt dat gebruikers worden geïnformeerd en leidt daarna de review.

Vóór de release bevestigt hij de scope en controleert hij dat elke riskante wijziging een rollbackpad heeft. Tijdens de release draait hij de deploychecklist, bekijkt hij de eerste minuten van de productiemetrics en roept hij vroeg een rollback uit. Daarna bevestigt hij dat de notes zijn uitgegaan en legt hij vast wat er in het proces moet worden verbeterd.

In een klein team rouleer je de rol wekelijks en schrijf je de checklist zo dat niemand impliciete kennis nodig heeft. Een monorepo met veel onafhankelijk uitgebrachte packages heeft meestal een releaseverantwoordelijke per package nodig, anders wordt de rol een bottleneck.

Wat zijn de belangrijkste KPI's voor releasemanagement?

Volg de DORA-metrics voor softwarelevering en voeg er zelf een toe: hoe lang het duurt voordat gebruikers worden geïnformeerd. Het onderzoek van DORA onderscheidt vijf metrics, verdeeld in doorvoer (change lead time, deployfrequentie, hersteltijd na mislukte deployments) en instabiliteit (change fail rate, deployment rework rate).

De gids van DORA definieert ze in gewone taal (dora.dev, software delivery metrics):

KPI	Wat het meet	Waar je op let
Change lead time	Tijd van commit in versiebeheer tot gedeployd in productie	Een stijgend getal betekent meestal wachtrijen in review of goedkeuring
Deployfrequentie	Hoe vaak je deployt, of de tijd tussen deployments	Dalende frequentie betekent dat batches groeien
Hersteltijd na mislukte deployment	Tijd om te herstellen van een deployment die direct ingrijpen vraagt	Problemen met rollback en alerting komen hier naar boven
Change fail rate	Aandeel deployments dat een rollback of hotfix vraagt	Stijgt als batches te groot zijn of testen te mager is
Deployment rework rate	Aandeel deployments dat ongepland is en door een productie-incident komt	Een teken dat fixes sneller live gaan dan lessen
Tijd tot gebruikers zijn geïnformeerd	Minuten van productiedeploy tot een gepubliceerde, voor gebruikers bedoelde note	Meet het zelf, geen framework levert het

Oudere bronnen noemen vier sleutelmetrics en noemen herstel "time to restore". De huidige gids gebruikt de vijf hierboven.

Dezelfde gids waarschuwt ertegen deze als doelen te behandelen. Een doel stellen als "alles deployt aan het eind van het jaar meerdere keren per dag" nodigt teams uit de cijfers te manipuleren, en de metrics zijn bedoeld om per applicatie of service te worden gelezen, niet gemengd over het hele bedrijf. Zijn praktische advies om ze allemaal te verbeteren is de omvang van elke wijziging te verkleinen, omdat kleinere wijzigingen makkelijker te reviewen zijn, sneller door de pipeline gaan en makkelijker te herstellen zijn.

Hoe past releasecommunicatie in het releasemanagementproces?

Het is stap zes, en heeft net als elke andere stap een eigenaar en een exitcriterium: notes gepubliceerd waar gebruikers lezen, en interne teams geïnformeerd. Teams slaan het het vaakst over, omdat deploytooling succes meldt zodra de code live is.

De goedkoopste manier om deze stap op schema te houden is de entry te schrijven wanneer de wijziging merget, niet wanneer de release live gaat. De pull request bevat al de titel, de auteur, de gekoppelde issue en de context. Een concept daaruit wordt bewerkt, niet een week later uit het hoofd geschreven. Dat is het idee achter changelog-automatisering: leid bij de merge een concept af, houd het vast voor goedkeuring door een mens en publiceer het dan overal vanuit één bron. Changeloop werkt zo: het stelt met AI entries op uit gemergede pull requests en houdt ze vast voor goedkeuring voordat er iets wordt gepubliceerd.

Twee varianten loont het vooraf te plannen. Support en sales hebben een andere note nodig dan klanten, en daar dienen interne release notes voor. Een door een incident gedreven release heeft geen tijd voor de normale conceptlus, dus houd een kort sjabloon klaar, zoals beschreven in noodrelease notes. De release notes template geeft je een startvorm voor de klantgerichte versie.

Hoe houd je het proces licht?

Automatiseer elk exitcriterium dat een machine kan controleren en bewaar mensen voor de afwegingen. Een groene pipeline, een deploymarker op de dashboards en een conceptentry voor elke gemergede pull request zijn controleerbaar. Of een rollbackplan geloofwaardig is, of de notes voor een klant te begrijpen zijn, vraagt een persoon.

Om het proces te testen kies je een release van vorige maand en vraag je of iemand buiten het team uit alleen het schriftelijke verslag kon opmaken wat er is uitgebracht, wie het goedkeurde, hoe het is geverifieerd en wanneer gebruikers zijn geïnformeerd. Elk gat is je volgende verbetering.

FAQ

Wat is het verschil tussen releasemanagement en change management? Releasemanagement zorgt dat een set wijzigingen wordt gebouwd, getest, gedeployd en aangekondigd. Change management, in de zin van ITIL, is het goedkeurings- en risicoproces rond elke wijziging. Teams die vaak uitbrengen vouwen goedkeuring in codereview en geautomatiseerde checks.

Hoe vaak moeten we uitbrengen? Zo vaak als je tests en rollbackpad toelaten, wat voor veel webteams dagelijks of vaker is. De richtlijn van DORA is de omvang van elke wijziging te verkleinen, omdat kleine wijzigingen makkelijker te reviewen en te herstellen zijn.

Hebben kleine teams een releasemanager nodig? Ze hebben de verantwoordelijkheden nodig, niet per se de titel. Rouleer de rol tussen engineers, geef degene aan de beurt een schriftelijke checklist en zorg dat iemand elk van de zeven stappen bezit.

Wat moet een releasechecklist bevatten? Scope bevestigd, pipeline groen op de commit die live gaat, rollbackpad benoemd, goedkeuring vastgelegd, smoke checks na de deploy, metrics vergeleken met de baseline, release notes gepubliceerd, support geïnformeerd en een review gepland. Houd het bij één pagina.

Release notes voorbeelden voor elk soort wijziging

Fri, 02 Oct 2026 00:00:00 GMT

De beste release notes voorbeelden zijn kort, noemen wie het treft en zeggen wat er daarna moet gebeuren. Hieronder staat één voorbeeld voor elk soort wijziging dat je gaat uitbrengen, met de reden waarom het werkt, zodat je de vorm kunt kopiëren en je eigen feiten kunt invullen.

Elk voorbeeld is verzonnen, voor een fictieve facturatie-app genaamd Tidepool.

Wat hebben goede release notes voorbeelden gemeen?

Ze vertellen gebruikers wat er veranderd is en wat ze er eventueel mee moeten, in de woorden van de gebruikers. Elk soort wijziging heeft een andere taak, dus de vorm verschuift per soort.

Soort wijziging	De entry moet zeggen	Waar het komt
Nieuwe feature	Wat de lezer nu kan, en wie het krijgt	Bovenaan de notes
Verbetering	Wat sneller of makkelijker werd, met een getal als je dat hebt	Na de features
Bugfix	Het symptoom dat de lezer zag, en dat het is opgelost	Na de verbeteringen
Breaking change	Wie het treft, de datum, de migratie	Altijd eerst
Beveiligingsfix	Wat blootlag, of het is misbruikt, wat te doen	Eerst
Deprecatie	Wat verdwijnt, de einddatum, de vervanger	Hoog in de notes
App-storenote	Eén gewone zin per wijziging, binnen de tekenlimiet	Storevermelding
Interne note	Wat er veranderde en wat klanten te vertellen	Support- en saleskanalen

Hoe ziet een goede note voor een nieuwe feature eruit?

Een goede featurenote opent met wat de lezer nu kan en noemt de plannen of rollen die het krijgen. De implementatie slaat hij over.

Stuur facturen in de taal van de klant. Je kunt nu per klant een taal kiezen, en hun facturen, herinneringen en betaalpagina volgen die taal. Frans, Duits, Spaans en Portugees zijn beschikbaar op alle plannen. Stel het in op de pagina van de klant, onder Factuurvoorkeuren.

De kop is een zin die de lezer hardop zou zeggen, en de tekst geeft bereik en vindplaats. Een lezer die alleen de vette regel scant, weet nog steeds wat er is uitgebracht. De bredere methode staat in hoe schrijf je release notes.

Hoe ziet een goede note voor een verbetering eruit?

Een verbeteringsnote beschrijft een verandering die de lezer zal voelen, en zet er een gemeten getal bij als dat bestaat. Zonder getal zeg je wat de lezer niet meer hoeft te doen.

De factuurlijst laadt ongeveer drie keer sneller. Accounts met meer dan 5.000 facturen wachtten vroeger ongeveer negen seconden op de lijst. Nu opent hij in ongeveer drie. Geen actie nodig.

"Prestatieverbeteringen" vertelt de lezer niets, terwijl negen seconden tegenover drie een bewering is die ze maandagochtend kunnen nalopen. Het afsluitende "Geen actie nodig" beantwoordt de vraag die elke lezer heeft.

Hoe ziet een goede note voor een bugfix eruit?

Een bugfixnote beschrijft het symptoom dat de gebruiker zag, niet de oorzaak in de code, en zegt of ze iets opnieuw moeten doen. Fixes die niemand opmerkte kunnen in de lijst onderaan.

Opgelost: herinneringsmails twee keer verstuurd op de vervaldatum. Sommige klanten kregen twee identieke herinneringen als hun factuur op de laatste dag van een maand verviel. Dit is opgelost. Reeds verstuurde herinneringen worden niet beïnvloed, en niemand hoeft iets opnieuw te versturen.

De kop begint met "Opgelost" zodat een scanner hem in één oogopslag kan sorteren, en de echte voorwaarde (de laatste dag van de maand) volgt meteen.

Hoe schrijf je release notes voor een breaking change?

Een breaking-changenote begint met de datum en de getroffen groep en geeft de migratie in dezelfde entry. Hij staat vooraan in de release notes, omdat het de ene entry is die een lezer niet mag missen.

Webhook-handtekeningen worden verplicht op 1 december 2026. Vanaf die datum stuurt Tidepool geen ongesigneerde webhook-payloads meer. Dit treft iedereen die webhooks ontvangt zonder de header Tidepool-Signature te controleren. Om te migreren verifieer je de header met het geheim onder Instellingen, Ontwikkelaars. Als je handtekeningen al verifieert, is er geen actie nodig.

De datum staat in de kop, dus hij overleeft een vluchtige blik. De getroffen groep wordt benoemd naar wat ze doen, en de laatste zin laat mensen die al in orde zijn los, wat de supportlast verlaagt. De gids over breaking changes behandelt hoe je beslist of een wijziging meetelt.

Hoe ziet een note over een beveiligingsfix eruit?

Een beveiligingsnote zegt wat er blootlag, of iemand het heeft misbruikt, wie het treft en wat ze moeten doen. Houd het feitelijk en rustig.

Beveiliging: links voor wachtwoordherstel konden opnieuw worden gebruikt. Tussen 3 en 17 september 2026 bleef een link voor wachtwoordherstel geldig nadat hij een keer was gebruikt. We vonden geen aanwijzing dat dit is misbruikt. Het is opgelost, en alle openstaande herstellinks zijn ongeldig gemaakt. Als je in die periode een herstel hebt aangevraagd, vraag dan een nieuwe link aan.

Het exacte venster laat een lezer zijn eigen blootstelling beoordelen, en de zin over misbruik beantwoordt de eerste vraag die iedereen stelt. "Een mogelijk probleem" leest als verhulling, dus zeg wat je weet.

Hoe schrijf je een deprecatiebericht?

Een deprecatiebericht noemt wat wordt verwijderd, geeft een vaste einddatum en wijst naar de vervanger.

Het v1-endpoint voor facturen is gedeprecieerd en eindigt op 1 maart 2027. GET /v1/invoices blijft werken tot 1 maart 2027 en geeft daarna 410 Gone terug. Gebruik GET /v2/invoices, dat dezelfde velden teruggeeft plus currency. Antwoorden van v1 bevatten nu een Sunset-header met de einddatum. Een migratiegids naast elkaar staat in de docs.

De naam van het endpoint staat in de kop, omdat de getroffenen daarop zoeken, en de vervanger staat naast de verwijdering. De Sunset-header vertelt ontwikkelaars welke aanroepen nog de oude versie gebruiken. De uitgebreidere behandeling staat in een API deprecieren.

Hoe ziet een release note voor een app store eruit?

Een app-storenote is twee of drie gewone zinnen, omdat de meeste mensen alleen de eerste regel lezen. Begin met de wijziging die een gebruiker zou opmerken.

Scan een papieren bonnetje en Tidepool vult bedrag, datum en leverancier in. Donkere modus volgt nu de instelling van je telefoon. We losten ook een crash op bij het openen van een factuur vanuit een melding.

De nuttigste wijziging staat eerst, en de fix noemt de situatie die crashte. Er is geen versienummer en geen "bugfixes en verbeteringen". Release notes voor mobiele apps behandelt de storespecifieke regels.

Wat hoort in een interne release note?

Een interne note is de versie voor support en sales. Hij voegt toe wat de publieke note weglaat: wat je moet zeggen, en wat je niet mag beloven.

Meertalige facturen vandaag uitgebracht (alle plannen). Support: klanten stellen de taal in onder Factuurvoorkeuren, en bestaande facturen houden hun oorspronkelijke taal. Italiaans is er nog niet. Sales: dit is open voor elk plan, positioneer het dus niet als upgrade.

Elke doelgroep krijgt een eigen gelabelde regel, en de note trekt de grens ("Italiaans is er nog niet") voordat een klant ernaar vraagt. Het artikel over interne release notes behandelt vorm en kanalen.

Hoe ziet een slechte release note eruit, herschreven?

Een slechte release note somt op wat het team deed in plaats van wat de lezer krijgt. Herstel dat door de uitkomst naar voren te halen en het interne jargon te schrappen.

Voor:

v3.8.1 Reminder-scheduler gerefactored. Race condition in ReminderJob opgelost. bull bijgewerkt naar 4.12. Diverse verbeteringen.

Na:

Herinneringsmails gaan niet meer dubbel de deur uit. Klanten met een factuur die op de laatste dag van een maand verviel, konden twee herinneringen krijgen. Dat is opgelost, en reeds verstuurde herinneringen hoeven niet opnieuw te worden verstuurd. Geen actie nodig.

Ook in 3.8.1: bull bijgewerkt naar 4.12.

De dependency-update zakte naar een voetregel, en de race condition werd een symptoom dat een klant zou herkennen.

Hoe houd je release notes consistent over releases heen?

Schrijf elke entry op het moment dat de wijziging wordt gemerged, en laat een persoon hem goedkeuren voordat hij live gaat.

Changeloop werkt zo: het stelt met AI een entry op uit elke gemergede pull request en houdt die vast tot een mens hem goedkeurt. De goedkeuringsstap is waar een redacteur de bovenstaande regels toepast. Om eerst het format vast te leggen begin je bij de release notes template, en bekijk changelog-voorbeelden voor hoe afgeronde pagina's eruitzien.

FAQ

Wat zijn nieuwe release notes? Nieuwe release notes zijn het bericht dat met de laatste release van een product wordt gepubliceerd en beschrijft wat er veranderd is en wat gebruikers moeten doen. Ze dekken features, verbeteringen, fixes en breaking changes.

Wat is het verschil tussen een release note en een changelog? De changelog bewaart alles, voor iedereen die de volledige geschiedenis wil. Een release note kiest daaruit: één release, geschreven voor de lezers die beslissen of die hen aangaat. De uitgebreidere vergelijking staat in changelog vs release notes.

Wat betekent release notes? Release notes vertellen gebruikers wat er in een release veranderde. De term dekt alles wat uitlegt wat er is uitgebracht, van een "Wat is nieuw"-tekst in een app store tot een pagina op de website van een bedrijf.

Hoe lang moet elke release note-entry zijn? Twee tot vier zinnen volstaan voor de meeste entries: de uitkomst, wie het treft en wat te doen. Een breaking change of een beveiligingsfix mag langer zijn omdat die een datum of een migratie nodig heeft.

Stripe API-versionering: hoe het werkt en wat je kopieert

Fri, 02 Oct 2026 00:00:00 GMT

Stripe API-versionering werkt op datum. Elk account is vastgepind op een API-versie die naar een releasedatum is vernoemd, en elk afzonderlijk verzoek kan die pin overschrijven met een Stripe-Version-header. Op het moment van schrijven (oktober 2026) is de huidige versie in de docs van Stripe 2026-09-30.endive, en hetzelfde schema is iets wat een veel kleinere API in een weekend kan overnemen.

Elk Stripe-feit hieronder komt van de eigen pagina's van Stripe, gelinkt waar het wordt gebruikt.

Mechanisme	Wat Stripe doet	Bron
Versienaam	Een datum, sinds 2024 plus een releasenaam (`2026-09-30.endive`)	Versioning
Standaardversie	Vastgepind op het account, te wijzigen in Workbench	Versioning
Override per verzoek	`Stripe-Version`-header, of de SDK-optie	Upgrades
Webhooks	Gerenderd in de versie die op het endpoint is ingesteld	Upgrades
Frequentie	Maandelijkse releases zonder breaking changes, twee keer per jaar een major release	Versioning
Oude versies	Blijven werken via interne versiewijzigingsmodules	Engineering post

Hoe werkt Stripe API-versionering?

Stripe geeft elk account een standaard API-versie, en elk verzoek dat geen versie noemt gebruikt die. Aanroepers kiezen zelf wanneer ze overstappen, door de standaard te wijzigen of door een versie op afzonderlijke verzoeken in te stellen.

Volgens de engineering post van Stripe wordt het account vastgepind bij het eerste API-verzoek: het account wordt "automatically pinned to the most recent version available", en vanaf dan krijgt elke aanroep die versie impliciet toegewezen.

De versiestring is een datum. Sinds de release 2024-09-30.acacia draagt hij ook een naam, zoals in 2026-09-30.endive. De datum ordent de versies, en de naam vertelt tot welke major-releasefamilie een versie behoort.

Hoe kies je een versie per verzoek?

Stuur de Stripe-Version-header mee met het verzoek, of stel de versie in de SDK in. De upgradegids van Stripe toont de headervorm, en dezelfde aanroep werkt in live- en testomgevingen.

curl https://api.stripe.com/v1/charges \
  -u "$STRIPE_SECRET_KEY:" \
  -H "Stripe-Version: 2026-09-30.endive"

De gids van Stripe merkt op dat wanneer je de versie globaal of per verzoek in een SDK instelt, de responseobjecten in die versie terugkomen.

Stripe raadt ook af om op de accountstandaard te leunen. In zijn eigen woorden: geef de versie voor elk verzoek op, met de header of een vastgepinde SDK, zodat jouw code de versie bepaalt en een dashboardinstelling niet.

SDK's pinnen per taal anders. De docs zeggen dat recente versies van de dynamisch getypeerde libraries de API-versie gebruiken die de nieuwste was toen die SDK-release uitkwam, en dat sterk getypeerde (Java, Go en .NET) eraan vast zitten. Een libraryversie installeren is in feite een API-versie kiezen.

Wat gebeurt er met webhooks als de versie verandert?

Een webhook-event wordt gerenderd in de API-versie die aan het endpoint hangt, niet in de versie die je servercode gebruikt. De docs van Stripe zeggen dat events de versie gebruiken die bij het aanmaken van het endpoint is ingesteld, en anders de accountstandaard. Je SDK-versie wijzigen verandert niet wat je webhookhandler ontvangt.

Je verzoekpad en je eventpad kunnen dus op twee verschillende versies zitten. Bij event destinations stel je snapshot_api_version alleen in wanneer je de destination aanmaakt, dus een andere versie betekent een nieuwe destination.

Het upgradepad van Stripe hiervoor is een parallelle run. Maak een nieuw endpoint op de doelversie, stuur dezelfde events naar beide, leer de handler er een te verwerken en de andere te negeren, schakel dan over en zet het oude endpoint uit. Omdat elk event tijdens de overlap twee keer binnenkomt, moet de handler idempotent zijn. Dat is een goed patroon om te kopiëren voor elke API die events uitzendt, en een webhook-changelog is waar je de payloadwijzigingen aankondigt die dat nodig maken.

Wat zijn de maandelijkse en de major releases?

Sinds de release 2024-09-30.acacia brengt Stripe maandelijks een nieuwe API-versie uit zonder breaking changes, en geeft het twee keer per jaar een nieuwe major release uit die begint met een versie met breaking changes. Op de versioningpagina staat dat je naar elke maandelijkse release kunt upgraden zonder je code aan te passen, terwijl een major release wijzigingen kan vereisen.

Major releases dragen namen. De versioningpagina noemt Basil als voorbeeld, en de aankondiging van Stripe over het proces zegt dat de namen van planten komen, te beginnen met Acacia, en dat maandelijkse releases de naam van de voorafgaande major release houden, zodat de naam aangeeft dat ze veilig zijn om naar te upgraden. De changelog van Stripe toont de namen die in gebruik zijn, en op het moment van schrijven is de nieuwste entry 2026-09-30.endive.

De datum beantwoordt dus "hoe nieuw", en de naam beantwoordt "is dit een breaking grens". De aankondiging van Stripe laat ook ruimte voor uitzonderingen: het behoudt zich het recht voor een breaking change buiten de cyclus uit te brengen als een integratie er anders ernstig door zou worden geraakt. De aankondiging staat op Stripe's new API release process.

Wat is de nieuwste versie van de Stripe API?

Op het moment van schrijven (oktober 2026) staat op de versioningpagina van Stripe dat de huidige versie 2026-09-30.endive is, en de changelog noemt dezelfde versie als de nieuwste. Stripe publiceert maandelijks een nieuwe versie, dus elke string die in een artikel staat veroudert snel. Lees de actuele changelog voordat je iets pint, en pin de versie waartegen je hebt getest.

Hoe houdt Stripe oude versies werkend?

Stripe houdt oude versies in leven door elke breaking change als een zelfstandige versiewijzigingsmodule te schrijven en de modules achterwaarts toe te passen vanaf de nieuwste vorm van de data. De engineering post over API-versionering beschrijft het mechanisme.

Elke module verklaart wat hij wijzigt, documenteert de wijziging en bevat een transformatiefunctie. De post geeft het voorbeeld van een veld dat van string naar hash verandert. Om een response te bouwen bepaalt het systeem de doelversie, loopt dan terug in de tijd en past elke module toe die het onderweg tegenkomt tot het die versie bereikt.

Uit dat ontwerp volgen twee neveneffecten, en de post noemt ze allebei. Omdat modules de velden en resources verklaren die ze raken, kan Stripe zijn API-changelog bij deployment daaruit genereren. En omdat de versie van het account bekend is, kan de documentatie zich eraan aanpassen en waarschuwen voor achterwaarts incompatibele wijzigingen sinds die versie.

Wat kost het, en wat moet een kleinere API kopiëren?

Versionering kost engineeringaandacht, en Stripe zegt dat zelf. De engineering post erkent een onderhoudslast en noemt het doel dat hoe minder je over oud gedrag hoeft na te denken bij het schrijven van nieuwe code, hoe beter. Hij beschrijft ook lichte API-reviews vóór de release, om een versiewijziging helemaal te vermijden.

Een kleine API kan zich geen modulereeks voor elke oude versie veroorloven, en heeft er ook geen nodig. Kopieer de onderdelen die de waarde dragen:

Gedateerde versies. Een datum vraagt geen oordeel over wat "major" is, en aanroepers kunnen hem lezen. Het artikel over beste practices voor API-versionering vergelijkt dit met URL- en headerschema's.
Een vastgepinde standaard. Pin het account of de key bij eerste gebruik op de versie, zodat de API nooit onder een werkende integratie verschuift.
Een override per verzoek. Een header waarmee een aanroeper een nieuwe versie op één aanroep kan testen, in productie, voordat hij zich vastlegt.
Een versie op het webhook-endpoint. Eventpayloads zijn de plek waar aanroepers het vaakst worden verrast.
Eén changelog-entry per versie. Laat hem de versie, de datum, de getroffenen en wat te doen noemen. Wat telt als breaking is de toets voor wat überhaupt in een nieuwe versie hoort, en het artikel over de API-changelog behandelt de entry zelf.

Sla de modulereeks over tot het aantal ondersteunde versies het afdwingt. Twee of drie live versies lukken met een paar vertakkingen en een sunsetdatum, wat een API-versie uitfaseren doorloopt.

Als je een gedateerde changelog publiceert, is de versiegeschiedenis zo goed als haar entries. In Changeloop wordt uit elke gemergede pull request een conceptentry aangemaakt die door een mens wordt goedgekeurd voordat hij op de changelogpagina en in de feed verschijnt. Daar wordt een entry per versie geschreven, en de ene menselijke poort is de review die zegt wat een aanroeper moet doen.

FAQ

Wat is de nieuwste versie van de Stripe API? Op het moment van schrijven (oktober 2026) staat op de versioningpagina van Stripe dat de huidige versie 2026-09-30.endive is. Stripe geeft maandelijks een nieuwe versie uit, dus controleer de changelog voordat je pint, en schrijf de versie in je code in plaats van op de accountstandaard te vertrouwen.

Hoe stel ik de Stripe API-versie in op een verzoek? Stuur de Stripe-Version-header mee, bijvoorbeeld Stripe-Version: 2026-09-30.endive, of stel de versie in je server-side SDK globaal of per verzoek in. Zonder een van beide gebruikt een verzoek de standaardversie van je account, die je in Workbench instelt.

Gebruiken webhooks dezelfde Stripe API-versie als mijn verzoeken? Niet noodzakelijk. Webhook-events gebruiken de versie die bij het aanmaken van het endpoint is ingesteld, en de accountstandaard als er geen is ingesteld. Je SDK upgraden verandert de payload die je webhookhandler ontvangt niet, dus upgrade endpoints apart en test ze parallel.

Is datumversionering in Stripe-stijl geschikt voor een kleine API? Gedateerde versies, een vastgepinde standaard, een header per verzoek en één changelog-entry per versie zijn goedkoop en het kopiëren waard. De interne reeks versiewijzigingsmodules niet, tot je veel oude versies tegelijk ondersteunt. Begin met twee live versies en een sunsetdatum voor de oudste.

Wie schrijft de changelog, en wie zou dat moeten doen

Tue, 22 Sep 2026 00:00:00 GMT

Vraag een team wie de changelog schrijft en het eerlijke antwoord is meestal "wie het zich herinnert", wat hetzelfde faalpatroon is dat een changelog-item afdwingen in CI bestaat om op mechanisch niveau op te lossen. Maar het afdwingen dat een item bestaat beslist niet wie gekwalificeerd is om er een goede te schrijven, en teams die die vraag overslaan vallen doorgaans standaard terug op wie het makkelijkst te verplichten is, meestal de PR-auteur, zonder te checken of dat ook echt de persoon is die het goed kan schrijven.

Waarom is de PR-auteur niet automatisch de beste changelog-schrijver?

Omdat ze de implementatie kent, niet per se de impact, en dat zijn verschillende soorten kennis. Waar stoppen conventional commits behandelt deze kloof vanaf de commitbericht-kant: fix(auth): reject expired refresh tokens is correct en vertelt een klant niets, en wie die fix schreef is vaak de persoon die het minst is toegerust om het te vertalen, omdat ze uren in termen van de bug heeft gedacht en het buitenperspectief kwijt is van wat een gebruiker daadwerkelijk heeft ervaren. Dit is dezelfde reden waarom technisch schrijvers als beroep bestaan: het vertalen van implementatie naar impact is een aparte vaardigheid ten opzichte van het bouwen van het ding zelf, en het vergt oefening ongeacht hoe goed de engineer zelf in de code is.

Betekent dat dat product of support elk item in plaats daarvan zou moeten schrijven?

Nee, want zij hebben de omgekeerde kloof: ze weten wat belangrijk is voor gebruikers maar niet altijd wat er daadwerkelijk is uitgeleverd, wat items oplevert die leesbaar maar af en toe verkeerd zijn qua omvang, een "ondersteunt nu X"-claim voor een feature die nog achter een flag zit, of een fix beschreven als compleet terwijl die maar één van drie gevallen dekt. Het faalpatroon van door ontwikkelaars geschreven items is onleesbaar-maar-accuraat; het faalpatroon van door PM's geschreven items is leesbaar-maar-ongeverifieerd. Geen enkele rol bezit beide helften van wat een goed item nodig heeft.

Rol	Krijgt meestal goed	Krijgt meestal fout
Ontwikkelaar die de code schreef	Exacte omvang van wat er veranderde	Het inkaderen voor iemand die het niet bouwde
PM of supportlead	Waarom het telt voor de gebruiker	Precieze grenzen van wat er echt is uitgeleverd
Toegewijde changelog-eigenaar	Consistente stem, toetst omvang	Heeft beide bovenstaande nodig om tegen te toetsen

Hoe ziet een werkend eigenaarschapsmodel er eigenlijk uit?

Een concept van wie het dichtst bij de verandering staat, gereviewd door wie het dichtst bij de gebruiker staat, met één benoemde persoon verantwoordelijk voor de uiteindelijke formulering in plaats van dat iedereen aanneemt dat iemand anders problemen zal opvangen. Het concept moet vooral bestaan en accuraat zijn, meer dan dat het goed moet zijn; een ruwe, door een ontwikkelaar geschreven zin die correct zegt wat er is veranderd is een beter startpunt dan een gepolijste maar ongeverifieerde, omdat herschrijven voor duidelijkheid makkelijker is dan herschrijven voor correctheid. De reviewstap is waar een PM of supportlead het concept leest en de ene vraag stelt die de leesbaarheidskloof vangt: zou ik dit begrijpen als ik de code niet had gezien.

Zou altijd dezelfde persoon verantwoordelijk moeten zijn, of roteert dat?

Benoemd en stabiel wint van roterend, in ieder geval voor de uiteindelijke goedkeuring. Een roterende eigenaar betekent dat elk item wordt gereviewd door iemand die de conventies van het team vanaf nul opnieuw afleidt, wat precies is hoe de stem van item tot item afdrijft en een lezer begint te merken dat de changelog door een comité is geschreven. Eén persoon, of een zeer kleine stabiele groep, verzamelt de afwegingen na verloop van tijd, wanneer je "verbeterd" zegt versus het specifieke getal noemt, wanneer een fix zijn eigen item nodig heeft versus opgaat in een batch, en dat oordeel is meer waard dan het werk gelijkmatig verdelen.

Concept (ontwikkelaar, uit de PR):
"Fixed pagination cursor not respecting the `sort` param
in some edge cases."

Gereviewd (changelog-eigenaar, getoetst aan de echte PR):
"Opgelost: op datum gesorteerde exports konden resultaten
buiten volgorde retourneren voorbij de eerste pagina.
Nu consistent op alle pagina's."

Heeft een klein team zoveel proces nodig voor één regel tekst?

Niet de rollen als aparte personen, maar de twee stappen tellen nog steeds, zelfs solo. Een team van één persoon is zowel de ontwikkelaar als de reviewer, en de discipline die op die schaal overleeft is de review als een aparte mentale pas doen, niet direct van het schrijven van de fix naar het publiceren van een beschrijving ervan in dezelfde adem springen. De valkuil op kleine schaal is de tweede pas helemaal overslaan, niet het ontbreken van een tweede persoon, omdat niemand van buitenaf het afdwingt, en de nauwkeurigheidskloof die die pas bestaat om te vangen verdwijnt niet alleen omdat dezelfde persoon in theorie haar eigen blinde vlek zou kunnen opmerken.

Wat gebeurt er als niemand verantwoordelijk is voor het uiteindelijke item?

De changelog verslechtert ongelijkmatig in plaats van compleet te falen, wat erger is omdat niemand het merkt totdat een lezer het aanwijst. Sommige items blijven scherp omdat wie ze schreef erom gaf; andere worden vaag, "diverse verbeteringen en bugfixes", omdat wie ze schreef snel bezig was en niemand het opmerkte voor publicatie. De formaatbeperkingen van Keep a Changelog vangen structurele drift, ontbrekende datums, verkeerde categorieën, maar niets in een template vangt een vaag item dat technisch goed geformatteerd is, wat precies de kloof is die een benoemde eigenaar er is om te dichten.

FAQ

Zou de changelog-eigenaar een engineering- of een productrol moeten zijn? Beide kunnen werken als de persoon zowel technische vaardigheid heeft om de omvang te verifiëren als genoeg afstand van de implementatie om voor een buitenstaande lezer te schrijven; de titel telt minder dan of ze beide helften kan doen, of weet aan wie te vragen voor de helft die ze niet kan.

Is een roterend, wachtdienst-achtig schema ooit geschikt voor changelog-eigenaarschap? Voor volume soms, als het team te klein is voor één persoon om alles te reviewen; voor stem en oordeel niet, want dat is precies wat rotatie eroderen. Een rotatie die de conceptlast deelt terwijl één stabiele reviewer behouden blijft krijgt het voordeel zonder de drift.

Wat is het snelste teken dat er iets mis is met de huidige eigenaarschapsopzet? Items die accuraat maar onleesbaar zijn, of leesbaar maar verkeerd qua omvang, in een patroon dat volgt wie ze schreef. Als kwaliteit correleert met de auteur in plaats van consistent te blijven, is eigenaarschap de kloof, niet schrijfvaardigheid.

Vermindert automatisering hoeveel eigenaarschap ertoe doet? Het vermindert hoeveel schrijven nodig is, niet hoeveel oordeel nodig is. Changelog-automatisering behandelt wat een pipeline veilig kan genereren, opmaak, publicatie, cross-posting; formulering, groepering en wat telt als vermeldenswaard blijven menselijke beslissingen ongeacht hoeveel van de pipeline geautomatiseerd is.

Wat als de PR-auteur en de reviewer het oneens zijn over de formulering? Het is aan de reviewer, want de vraag die ze beantwoorden, zou een buitenstaande lezer dit begrijpen, is precies degene die de rol moet beschermen. Dat maakt de kijk van de engineer niet waardeloos: als het meningsverschil over accuraatheid gaat in plaats van over formulering, geeft de reviewer toe, want omvang is de helft die de auteur moet kloppen. De twee soorten meningsverschil scheiden, formulering versus accuraatheid, voorkomt dat de meeste hiervan een impasse worden.

Noodrelease notes: schrijven onder echte tijdsdruk

Tue, 22 Sep 2026 00:00:00 GMT

De meeste release notes worden geschreven nadat de code klaar is, rustig gereviewd, en gepubliceerd volgens een schema dat niets te maken heeft met hoe dringend iemand ze moet lezen. Een noodrelease, een beveiligingspatch, een bug met dataverlies, een storingsherstel, keert al die voorwaarden tegelijk om: de notes moeten bestaan voordat de meeste mensen normaal zouden beginnen met schrijven, krijgen nauwelijks review, en worden gelezen door mensen die bezorgd zijn in plaats van ontspannen. Hoe schrijf je release notes behandelt het normale proces; dit gaat over wat er verandert als er geen tijd meer is om het te volgen.

Wat is het enige dat een noodrelease note absoluut goed moet doen, als er verder niets klopt?

Of de lezer iets moet doen, gezegd in de eerste zin, zonder enige inkadering ervoor. Een lezer die op een door een incident gedreven release note stuit is vaak al bezorgd, omdat ze over het probleem heeft gehoord via een statuspagina, een supportthread, of haar eigen gebruikers, en een note die opent met context vóór de actie-item leest als het achterhouden van informatie precies in de omstandigheden waarin achterhouden het slechtst leest. "Geen actie nodig, dit patcht een kwetsbaarheid die geen gebruikersdata vereiste om uit te buiten" en "Update onmiddellijk: deze release lost een bug op die de data van het ene account aan een ander kon tonen" zijn beide één zin, en beide doen het hele werk dat een in paniek geraakte lezer nodig heeft voordat ze iets anders leest.

Geldt de gebruikelijke redactieronde nog als er geen tijd is voor een?

Het instinct om te comprimeren overleeft zelfs wanneer het proces met meerdere concepten dat het normaal produceert dat niet doet. De herschrijving beschrijft het inkorten van een breedsprakig eerste concept tot de essentiële zin; onder tijdsdruk is er vaak geen eerste concept om in te korten, wat betekent dat de discipline in je hoofd moet draaien terwijl je schrijft in plaats van als aparte ronde achteraf. De snelste manier om het te benaderen: schrijf de zin die je hardop zou zeggen tegen iemand die vraagt "wat moet ik weten", stop dan, want die zin is meestal zowel de snelste om te produceren als de enige die een lezer in die staat daadwerkelijk zal verwerken.

Normale release note	Noodrelease note
Geschreven na codereview, vóór publicatie	Vaak geschreven samen met de fix, vóór volledige review
Geoptimaliseerd voor scanbaarheid over veel items	Geoptimaliseerd voor één item dat geïsoleerd wordt gelezen, onder stress
Kan detail uitstellen naar een gelinkte changelog	Zou het ene belangrijkste feit vooraan moeten zetten
Inkadering en context zijn welkom	Inkadering vóór de actie-item leest als vertraging

Is het ooit oké om een note te publiceren voordat je helemaal zeker weet wat het probleem heeft veroorzaakt?

Ja, als de note eerlijk is over die onzekerheid in plaats van een vertrouwen te suggereren dat je niet hebt. "We hebben een fix uitgerold voor verhoogde foutpercentages bij het afrekenen; we bevestigen nog de grondoorzaak en zullen deze note bijwerken" is verdedigbaar en koopt correct tijd; een note die een specifieke oorzaak vermeldt die je eigenlijk niet hebt bevestigd is het soort gok dat later wordt wat mensen tegen je aanhalen als het verkeerd blijkt te zijn. De discipline die hier telt is niet diagnosesnelheid, het is nooit laten dat het vertrouwen van de note het werkelijke vertrouwen van het team overtreft, omdat een verkeerde technische bewering in een noodnote meer schade aan vertrouwen doet dan een toegegeven onbekende.

Te zeker, niet geverifieerd:
"Fixed: a race condition in the payment webhook handler
caused duplicate charges."

Eerlijk onder tijdsdruk:
"Opgelost: sommige klanten werden dubbel belast voor
één bestelling. We hebben nieuwe gevallen gestopt en
vergoeden getroffen accounts binnen 24 uur. Grondoorzaak
wordt onderzocht."

Zou een noodnote moeten zeggen wat het probleem heeft veroorzaakt, of gewoon dat het is opgelost?

Zeg wat er is opgelost en wat de lezer zou moeten doen; bewaar de grondoorzaak voor een vervolgnote zodra die echt bekend is, niet geraden. Een lezer midden in een incident wil precies twee feiten, is dit opgelost en raakt het mij, en een verklaring van de grondoorzaak, zelfs een accurate, concurreert met die twee feiten om aandacht op het slechtst mogelijke moment om het te verliezen. De postmortem, apart gepubliceerd zodra het onderzoek klaar is, is waar de grondoorzaak thuishoort; de twee documenten mengen onder tijdsdruk produceert een note die langzamer is om te schrijven en langzamer om te lezen, het tegenovergestelde van wat een noodgeval nodig heeft.

Geldt het probleem van gedwongen updates uit mobiele apps hier ook?

Hetzelfde principe, verder gecomprimeerd. Release notes voor mobiele apps behandelt gedwongen updates, waarbij de note vóór alles de reden en de deadline moet vermelden omdat de lezer al geïrriteerd is over geen keuze te hebben; een noodrelease note voor het web is meestal opt-in voor de lezer in de zin dat ze kiest of ze erop reageert, maar hetzelfde instinct "vermeld eerst de beperking" geldt, alleen om een andere reden: geen irritatie, urgentie.

Hoe voorkom je dat een noodnote leest als een schuldbekentenis terwijl dat niet zou moeten?

Beschrijf de fix en het effect ervan, niet de schuld, en weersta de drang om overdreven je excuses aan te bieden, wat leest als opvulling voor een lezer die de twee feiten hierboven wil. "We hebben een bug gevonden en opgelost die sommige exports beïnvloedde" zegt wat er is gebeurd zonder er drama aan toe te kennen; "Het spijt ons ontzettend voor dit ernstige probleem dat onze gewaardeerde klanten heeft getroffen" vertraagt de nuttige informatie met een hele zin om een emotioneel moment te leveren waar de lezer niet om vroeg. Een korte, feitelijke note is niet kil, ze respecteert de werkelijke staat van de lezer, die onder echte druk ongeduld is, geen behoefte aan geruststelling.

FAQ

Zou een noodrelease note hetzelfde reviewproces moeten doorlopen als een normale? Een lichtere, geen: één snelle reviewer die controleert dat de note geen zekerheid overdrijft is de paar minuten waard die het kost, omdat het risico dat een ongereviewde technische bewering verkeerd is juist hoger is omdat ze snel is geschreven.

Is het oké om een noodnote te publiceren zonder link naar meer detail? Alleen kort. Een note zonder link werkt als het eerste dat wordt gepubliceerd; voeg er een toe naar een statuspagina of vervolg zodra een van beide bestaat, omdat een lezer die meer wil dan de ene zin die je gaf ergens naartoe moet kunnen, ook al zegt die plek "meer details volgen snel".

Zou een noodnote ooit helemaal overgeslagen moeten worden, zodat de fix stilletjes wordt uitgerold? Alleen voor problemen die geen enkele lezer had kunnen opmerken of erdoor getroffen kon zijn; als er enige kans is dat een lezer het probleem heeft ervaren, is de note wat haar vertelt dat het voorbij is, en stilte leest alsof het probleem misschien nog actief is.

Hoe lang zou een noodnote vastgepind of prominent moeten blijven nadat het incident is opgelost? Tot het venster van directe onrust sluit, meestal een dag of twee, dan kan ze opgaan in de normale changelog als elk ander item; een note die weken vastgepind blijft, begint te lezen als een onopgeloste zorg in plaats van een opgeloste.

Protobuf breaking changes: wat overleeft op de wire

Tue, 22 Sep 2026 00:00:00 GMT

Een REST-API verandert wanneer een JSON-vorm verandert, en het grootste deel van die vorm is zichtbaar in het antwoord dat je in een browser kunt lezen. Een gRPC-API verandert wanneer een .proto-bestand verandert, en het binaire wire-formaat van Protocol Buffers heeft eigen regels over wat een client kan verdragen die niets te maken hebben met wat de veldnamen zeggen. Twee wijzigingen die er in een diff even klein uitzien, een veld hernummeren tegenover er een toevoegen, vallen aan tegenovergestelde kanten van een lijn die breaking changes in het algemeen trekt: de ene is onzichtbaar voor elke bestaande client, de andere breekt ze allemaal tegelijk. Protobuf breaking changes onderscheiden van veilige wijzigingen betekent de eigen regels van het wire-formaat lezen, niet gokken op basis van hoe de wijziging eruitziet in een .proto-diff.

Waarom telt veldnummering meer dan veldnaam in Protobuf?

Omdat het wire-formaat velden codeert op nummer, niet op naam. De gegenereerde code in elke taal leest en schrijft die nummers; de veldnaam email in je .proto-bestand is een gemak voor mensen dat nooit de binaire bytes raakt die over het netwerk worden verzonden. Een veld hernoemen, email naar email_address, is veilig op de binaire wire zolang het nummer hetzelfde blijft, wat ontwikkelaars verrast die gewend zijn aan REST, waar een hernoemde JSON-key precies het soort verandering is dat een client breekt. De uitzondering is juist dat REST-geval: de ProtoJSON- en tekstformaten serialiseren de naam, dus een hernoeming breekt JSON-transcoding (bijvoorbeeld een grpc-gateway), bestanden in tekstformaat en field masks. Datzelfde veld hernummeren, de naam behouden maar 1 veranderen in 7, is precies andersom: onzichtbaar in een codereview die alleen namen toont, en het corrumpeert elk bericht dat een client vanaf dat punt verstuurt of ontvangt.

Verandering	Veilig op de wire	Waarom
Veld hernoemen, nummer behouden	Binair ja, JSON en tekst nee	Binaire codering gebruikt het nummer; ProtoJSON en tekstformaat gebruiken de naam
Nummer van een veld veranderen	Nee	Elk bestaand bericht wordt nu als het verkeerde veld gelezen
Nieuw veld toevoegen met nieuw nummer	Ja	Oude clients negeren velden die ze niet herkennen
Veld verwijderen, oud nummer hergebruiken voor iets anders	Nee	Oude data wordt gedecodeerd in het verkeerde nieuwe veld
Type van een veld incompatibel veranderen (bijv. `int32` naar `string`)	Nee	De wire-codering verschilt per type

Wat maakt het verwijderen van een veld anders dan in een REST JSON-antwoord?

Het nummer wordt radioactief. Protobufs eigen richtlijnen raden aan het nummer van een verwijderd veld als reserved te markeren in plaats van het te laten hergebruiken, omdat hergebruik is waar de echte schade gebeurt: een client die nog code van vorige maand draait stuurt een bericht met het oude nummer van het veld voor de oude betekenis, en de server, die nu verwacht dat dat nummer iets anders betekent, interpreteert de data stilletjes verkeerd in plaats van ze ronduit af te wijzen. REST heeft geen equivalente valkuil, omdat een verwijderde JSON-key simpelweg stopt met verschijnen; er is geen manier waarop het verzoek van een oude client stilzwijgend als iets anders wordt geherinterpreteerd. Een .proto-bestand met reserved 4, 9, 12; bovenaan een bericht is een permanent litteken, en dat is het punt: het voorkomt dat het nummer wordt toegewezen aan een nieuw veld door iemand die de geschiedenis ervan niet kende.

message Invoice {
  reserved 4; // was `legacy_customer_id`, verwijderd op 2026-06-01
  reserved "legacy_customer_id"; // ook de naam, voor JSON/tekst
  string customer_id = 5;
  string status = 6;
}

Vereist het toevoegen van een veld ooit een changelog-item?

Meestal geen breaking-change-item, maar vaak wel een gewoon item, omdat "veilig op de wire" en "onzichtbaar voor een lezer die erom geeft" twee verschillende claims zijn. Een veld toevoegen aan een responsbericht kost structureel niets, oude clients decoderen het bericht en negeren het nieuwe veld automatisch. Maar iemand die een nieuwe integratie bouwt tegen die service heeft geen manier om te weten dat het veld bestaat tenzij iemand het haar vertelt, omdat niets aan een geslaagde build of een geslaagde test een nieuw optioneel veld zichtbaar maakt. Changelog van API behandelt in het algemeen wat een additief item aan lezers verschuldigd is; de gRPC-specifieke reden om er toch een te schrijven is dat er geen equivalent is van het doorbladeren van een REST-antwoord in een debugger om te merken dat er een nieuwe key is verschenen.

Hoe verschilt dit van wat GraphQL-aanroepers meemaken?

De regels voor toevoegingen komen overeen, maar de blootstelling verschilt. GraphQL-schemadeprecatie behandelt een model waarbij een client alleen de velden ontvangt die hij expliciet opvraagt, wat additieve wijzigingen in wezen risicovrij maakt en verwijderingen het enige echte gevaar. gRPC- clients daarentegen ontvangen wat de server ook stuurt en decoderen alles tegen hun eigen gecompileerde kopie van het schema; de blootstelling van een client is niet begrensd door wat hij opvroeg, alleen door wat zijn gegenereerde code kan lezen. Dat verschil is belangrijk voor het schrijven van changelogs: een GraphQL-item kan redelijkerwijs aannemen dat clients afgeschermd zijn van velden die ze niet opvroegen, en een gRPC-item kan dat helemaal niet aannemen.

Werkt het versioneren van een gRPC-service hetzelfde als REST's `/v1/`, `/v2/`?

Het mechanisme is anders, zelfs als de bedoeling hetzelfde is. Wat zijn v1 en v2 in een REST-API behandelt versionering als parallelle URL-paden die verschillende contracten bedienen; gRPC-services versioneren doorgaans via de packagenaam in het .proto-bestand zelf, payments.v1.InvoiceService wordt payments.v2.InvoiceService, wat de volledig gekwalificeerde servicenaam verandert die een client belt in plaats van een URL-segment dat hij opvraagt. Beide benaderingen lossen hetzelfde probleem op, een oud contract laten blijven werken terwijl er een nieuw bestaat, maar een team met een REST-achtergrond zoekt vaak op de verkeerde plek naar een versienummer en mist dat de package-declaratie dat werk doet.

Wat zou een gRPC-changelog-item eigenlijk moeten noemen?

Het bericht, het veldnummer, en of het additief is of een verwijdering die migratie vereist, in die volgorde van belangrijkheid voor een lezer die beslist of ze moet handelen. "shipping_address (veld 8) toegevoegd aan Order" vertelt een integrator alles wat nodig is om gegenereerde code bij te werken en het te gaan gebruiken. "Veld 4 gereserveerd op Invoice, legacy_customer_id is weg" vertelt haar te controleren of er nog iets in haar codebase dat veld leest, wat een REST-achtige notitie "een veld verwijderd uit het antwoord" niet met dezelfde urgentie communiceert, omdat REST-verwijderingen gewoon minder data teruggeven terwijl hergebruik van Protobuf-velden ze actief corrumpeert.

FAQ

Kan het type van een veld ooit worden veranderd zonder het wire-formaat te breken? Alleen binnen specifieke compatibele groepen die Protobuf documenteert, zoals int32 verruimen naar int64 in sommige gevallen. Behandel elke typewijziging als breaking tenzij je hem hebt gecontroleerd tegen Protobufs eigen compatibiliteitstabel; compatibiliteit aannemen door analogie met het typesysteem van een taal is hoe dit fout gaat.

Werkt het deprecaten van een veld in Protobuf zoals GraphQL's @deprecated-directive? Op vergelijkbare wijze: Protobuf ondersteunt een [deprecated = true]-veldoptie die tooling kan tonen. Geen van beide wordt afgedwongen: een GraphQL-server beantwoordt nog steeds een query naar een gedeprecieerd veld, en een protobuf-client codeert er nog steeds een. Beide zijn adviserend en hebben dezelfde changelog-ondersteuning nodig.

Is hernummeren ooit veilig als je elke client controleert? In een volledig gesloten systeem, in principe, maar het elimineert de hele veiligheidseigenschap waarvoor veldnummers bestaan, en "we controleren elke client" is een bewering die ophoudt waar te zijn zodra een build wordt gecachet, een deploy wordt vertraagd, of er een client wordt toegevoegd die niemand zich herinnerde. Reserveer het nummer in plaats van het te hergebruiken, ook intern.

Hebben gRPC-services een changelogpagina nodig zoals een publieke REST-API? Alleen als externe teams ze consumeren zonder .proto-diffs direct te lezen, dezelfde "wie zit er aan de andere kant"-test die interne API-changelogs in het algemeen toepast. Een gRPC-service die alleen wordt geconsumeerd door andere services van hetzelfde team kan vaak een formele changelog overslaan ten gunste van de commitgeschiedenis, omdat iedereen die het leest het schema al open heeft.

Changelog-bestandsformaten: JSON, YAML of gewoon Markdown

Thu, 17 Sep 2026 00:00:00 GMT

De meeste teams beginnen een changelog als Markdown-bestand omdat het de weg van de minste weerstand is: leesbaar in een diff van een pull request, leesbaar op GitHub zonder iets te renderen, en vertrouwd voor iedereen die ooit een README heeft geschreven. Die keuze werkt prima totdat iets anders dan een mens het bestand moet lezen, een pagina, een widget, een e-mailsamenvatting, en dan houdt het formaat op gratis te zijn. Changelog-automatisering behandelt de structurele eis in het algemeen, een type, een datum, een body en een link; dit gaat over welk bestandsformaat die structuur echt levert en wat het kost om daar te komen bij elk.

Wat is er mis met een simpele Markdown-changelog?

Niets, totdat iets het terug moet parsen naar velden. Een kop, een datum en een lijst eronder is triviaal te lezen voor een mens en oprecht lastig betrouwbaar te parsen, omdat Markdown geen schema heeft: de datum kan in de kop staan, vetgedrukt op de eerste regel, of helemaal ontbreken bij een oud item, en elk van die varianten is geldige Markdown die een mens correct leest en een parser niet. Teams die een Markdown-changelog automatiseren, eindigen meestal met een op maat gemaakte regex-parser die breekt zodra de opmaak van een item ook maar licht afwijkt, wat vaak gebeurt, omdat niets consistentie afdwingt bij het schrijven.

Wat levert een gestructureerd formaat je eigenlijk op?

Een garantie dat elk item dezelfde vorm heeft, gecontroleerd wanneer het item wordt geschreven in plaats van geraden wanneer het wordt gelezen. Een JSON- of YAML-bestand met een gedefinieerd schema, type, datum, versie, doelgroep, body, link, faalt luidruchtig als een verplicht veld ontbreekt, net zoals een strikte API-respons zou doen; een Markdown-bestand rendert gewoon wat er staat, correct of niet. Dat verschil is onzichtbaar tot de dag dat een script de datum van elk item nodig heeft om een feed te sorteren, en de helft van de items heeft die op een andere plek staan.

# CHANGELOG.yml
- date: 2026-09-05
  type: breaking
  version: v2
  audience: api
  body: "POST /invoices now rejects a currency mismatch instead of silently converting."
  link: /blog/api-changelog/

Betekent dat dat het mensleesbare bestand moet verdwijnen?

Nee, en proberen een YAML- of JSON-bestand tegelijk te laten dienen als wat een mens leest in een pull request is meestal een fout de andere kant op: een diff van geneste JSON reviewen is erger dan een zin proza reviewen, en een reviewer die een datastructuur mentaal moet parsen om een formuleringsfout te vangen, is een reviewer die uiteindelijk stopt met formuleringsfouten vangen. De twee formaten kunnen naast elkaar bestaan: gestructureerde data is de bron van waarheid die een automatiseringspipeline leest, en een gegenereerde Markdown- of HTML-weergave is wat een mens daadwerkelijk reviewt en leest, geproduceerd uit het gestructureerde bestand in plaats van er handmatig naast onderhouden.

Formaat	Mensleesbaar zoals het is	Machinaal parseerbaar zonder maatwerkcode	Veelvoorkomende faalmodus
Markdown	Ja	Nee	Inconsistente itemvorm breekt naïeve parsers
JSON	Slecht	Ja	Omslachtig; makkelijk handmatig naar ongeldige JSON te bewerken
YAML	Redelijk	Ja	Gevoelig voor witruimte; een verkeerde inspringing is een stille, geen luide parseerfout

Welk gestructureerd formaat is echt makkelijker handmatig te bewerken, JSON of YAML?

YAML, voor wie items met de hand schrijft in plaats van via een generator, omdat het het quoten en haakjes matchen wegneemt dat JSON vereist voor elke string en genest object. Het nadeel is dat de witruimtegevoeligheid van YAML op een manier stil faalt waarop de haakjesmismatches van JSON dat meestal niet doen: een JSON-parser wijst misvormde invoer regelrecht af, terwijl een YAML-parser een slecht ingesprongen bestand kan accepteren en het gewoon in de verkeerde structuur parst, wat een erger falen is omdat niets je vertelt dat het is gebeurd. Als items altijd alleen door een script worden geschreven, verdwijnt dit nadeel grotendeels en wordt het strengere parsen van JSON de veiligere standaardkeuze.

Heeft een changelogpagina zijn eigen gestructureerde formaat nodig, apart van het bestand dat het voedt?

Niet een apart formaat, hetzelfde anders gerenderd. Een changelogpagina behandelt hoe je de pagina zelf machineleesbaar maakt via een JSON-feed en schema.org-markup; die feed is gegenereerde output, geen tweede bron van waarheid die synchroon gehouden moet worden met het onderliggende bestand. Gestructureerde data op twee plekken handmatig onderhouden, een bronbestand en de feed van een pagina, is hoe de twee uit elkaar drijven, dus de bestandsformaatbeslissing die hier genomen wordt, zou het enige moeten zijn waaruit alles stroomafwaarts, pagina, widget, e-mail, gegenereerd wordt, nooit handmatig gekopieerd.

Is het migratiekosten waard om een bestaande Markdown-changelog om te zetten naar een gestructureerd formaat?

Meestal pas zodra automatisering het echte doel is, niet ervoor. Een eenpersoonsproject dat een Markdown-bestand publiceert in een GitHub-README heeft geen echte automatiseringsbehoefte, en het omzetten naar YAML koopt niets dan plichtplegingen. De conversie betaalt zichzelf terug op het moment dat meer dan één stroomafwaartse consument, een pagina, een samenvattingsmail, een publieke feed, dezelfde data moet lezen, omdat dat precies het punt is waarop de inconsistenties van een Markdown-parser zichtbaar verkeerde output beginnen te produceren in plaats van gewoon vervelend te zijn om te onderhouden.

FAQ

Kan een Markdown-changelog parseerbaar worden gemaakt zonder helemaal van formaat te wisselen? Gedeeltelijk, met frontmatter: een klein YAML-blok bovenaan elk item (datum, type, versie) naast een Markdown-body voor de proza. Dit levert de gestructureerde velden die een parser nodig heeft zonder het hele item in JSON of YAML te dwingen, en het is een redelijk middenweg voor een team dat nog niet klaar is voor een volledige migratie.

Maakt het bestandsformaat uit voor SEO of voor hoe een changelogpagina rankt? Niet direct. Zoekmachines lezen de gerenderde pagina, niet het bronbestand, dus het bestandsformaat is voor hen onzichtbaar; wat telt voor de pagina zelf is of hij op eigen kracht machineleesbaar is, wat een apart punt is van wat hem genereert.

Moet elk changelog-item door hetzelfde bestand lopen, of kunnen types over bestanden worden verdeeld? Eén bestand is simpeler tot het itemvolume het onhandig maakt om te diffen of te reviewen; opsplitsen per jaar of per categorie is een redelijke ontsnappingsklep zodra de diffs van één bestand te groot worden om zinnig te reviewen, maar het voegt een samenvoegstap toe voordat iets stroomafwaarts "alle items" als één lijst kan lezen.

Bestaat er een standaard changelog-bestandsformaat, zoals er een standaard is voor RSS? Niet een breed aangenomen. Keep a Changelog stelt een Markdown-conventie voor, en verschillende tools hebben hun eigen; een changeset is een Markdown-bestand met YAML-frontmatter dat het pakket en de bump noemt, precies het frontmatterpatroon dat hierboven is beschreven. Geen daarvan is een formaat dat andere tools out of the box lezen zoals RSS-lezers universeel RSS begrijpen.

Dubbele featureverzoeken: zonder de stem te verliezen

Thu, 17 Sep 2026 00:00:00 GMT

Drie klanten vragen in drie verschillende weken om dezelfde mogelijkheid, op drie verschillende manieren geformuleerd, en een triageproces gebouwd om duplicaten te vangen doet zijn werk: het groepeert ze, telt ze als één verzoek met drie stemmen, en de backlog blijft schoon. Dat is het makkelijke deel. Welke labels zijn de moeite waard behandelt groeperen op onderliggende capaciteit voordat je op formulering trieert als de mechanische fix voor duplicaten; wat het niet behandelt is wat er met de woorden zelf gebeurt zodra drie verzoeken één regel worden, en dat verlies is meestal groter dan het probleem van dubbeltellen dat het oploste.

Wat gaat er echt verloren als duplicaten worden samengevoegd?

De specifieke formulering die elke aanvrager gebruikte, die vaak informatiever is dan het stemaantal waarin het instort. De ene klant vraagt misschien om "een manier om gefilterde resultaten te exporteren", een andere om "CSV-export die mijn opgeslagen filters respecteert", en een derde om "export zonder verborgen kolommen". Alle drie zijn hetzelfde onderliggende verzoek, correct gegroepeerd, maar elke formulering draagt een net iets andere nadruk op wat voor die persoon belangrijk is, en een samenvoeging die alleen de formulering van de eerste indiening behoudt, gooit de andere twee helemaal weg. De telling overleeft; de textuur die iemand zou helpen de juiste versie van de feature te bouwen, niet.

Waarom maakt de textuur uit als het stemaantal al zegt dat er vraag bestaat?

Omdat vraag en ontwerp verschillende vragen zijn, en alleen de specifieke formulering beantwoordt de tweede. Tien stemmen op "export" vertelt een team dat de feature het waard is om te bouwen; het zegt niets over of "export" CSV, PDF, een geplande e-mail of een API-endpoint betekent, en een samenvoeging die negen van de tien originele indieningen laat vallen ten gunste van de formulering van de eerste kan de specificatie stilletjes versmallen tot wat die eerste aanvrager toevallig vroeg, zelfs als de andere negen iets subtiel anders wilden. Wat een featureverzoek eigenlijk moet vastleggen behandelt precies dit gat vanaf de intake-kant; duplicaten samenvoegen is waar het weer opduikt na de intake, precies op het punt waar een team het bereik van wat er echt gevraagd is het hardst nodig heeft.

Hoe ziet een samenvoegproces eruit dat de formulering bewaart in plaats van te weggooien?

Toevoegen in plaats van vervangen. Het canonieke item houdt één titel aan voor de backlogweergave, maar de originele formulering van elke samengevoegde indiening blijft eraan hangen, ofwel als een lijst citaten of als gelinkte bron-tickets, zodat iedereen die het item later beoordeelt het werkelijke bereik kan zien van wat mensen vroegen in plaats van de samenvatting van één teamlid ervan. Dit kost bijna niets om te bouwen, een veld op het ticket in plaats van een nieuw systeem, en het is het verschil tussen een samenvoeging die informatie comprimeert en een die alleen de weergave ervan comprimeert.

Feature: Gefilterde CSV-export
Stemmen: 12
Samengevoegde verzoeken:
  - "een manier om gefilterde resultaten te exporteren" (acct_4421)
  - "CSV-export die mijn opgeslagen filters respecteert" (acct_8832)
  - "export zonder verborgen kolommen" (acct_1097)
  ...

Verdient elk duplicaat het om te worden samengevoegd, of zijn er valse matches?

Sommige zijn valse matches, en "klinkt vergelijkbaar" behandelen als "is hetzelfde verzoek" is zijn eigen faalmodus. "Laat me mijn data exporteren" en "laat me alleen de gefilterde weergave exporteren" kunnen gegroepeerd worden door een trefwoordmatch op "exporteren" terwijl ze eigenlijk twee verschillende scopes van dezelfde algemene capaciteit beschrijven; ze samenvoegen blaast ofwel het stemaantal op voor het verkeerde ding of, erger, levert de smallere versie omdat die toevallig eerst aankwam. Een menselijke doorloop van de groepering, zelfs een snelle, vangt dit voordat het zich opstapelt; een automatische gelijkenismatch alleen zal te veel samenvoegen op vocabulaire en te weinig op intentie.

Wanneer moet dubbelecontrole eigenlijk plaatsvinden: bij intake of later?

Allebei, om verschillende redenen. Controle bij intake vangt het voor de hand liggende geval, een nieuw verzoek dat iets herhaalt dat al openstaat, voordat het ooit een eigen ongetrackt item wordt; een gelijkeniszoekopdracht tegen openstaande verzoeken op het moment van indienen handelt de meeste hiervan af zonder dat er een mens bij betrokken is. Een tweede ronde later, op een langzamer ritme, vangt het geval dat intake mist: twee verzoeken die op dat moment net verschillend genoeg geformuleerd waren om langs een trefwoord- of embeddingmatch te glippen, maar die, zodra een team een tiental varianten heeft gezien, blijken dezelfde onderliggende mogelijkheid te beschrijven. De tweede ronde overslaan laat bijna-duplicaten voor onbepaalde tijd verspreid staan onder aparte titels, elk met zijn eigen kleine stemmenaantal dat nooit optelt tot het aantal dat het gebouwd zou hebben gekregen.

Zou de aanvrager moeten weten dat zijn indiening is samengevoegd in een bestaand item?

Ja, en dit is dezelfde discipline als de klantfeedbacklus sluiten toegepast één stap eerder dan gebruikelijk: een aanvrager die iets indiende en nooit meer iets hoort, concludeert dat zijn verzoek nergens toe leidde, zelfs als het correct werd samengevoegd in een item met elf andere stemmen dat uiteindelijk werd uitgerold. Een korte bevestiging, "we hebben dit gecombineerd met een bestaand verzoek dat anderen ook hebben gedaan", kost één bericht en voorkomt dat een klant hetzelfde verzoek elke paar maanden opnieuw indient omdat hij geen zicht heeft op of het ooit echt werd bijgehouden.

Verandert samenvoegen wie krediet krijgt als de feature wordt uitgerold?

Het zou iedereen moeten omvatten, niet alleen wie het eerst indiende. De feedbacklus sluiten behandelt aanvragers laten weten wanneer hun wens wordt uitgerold; voor een samengevoegd item betekent dat elk account dat aan de samenvoeging hangt, niet alleen degene wiens formulering de canonieke titel werd, want vanuit het perspectief van elke aanvrager vroeg zij hierom en het werd uitgerold, ongeacht wiens formulering een triageproces toevallig bewaarde. Met Changeloop betekent dat dat de pull request elke gekoppelde issue noemt (Fixes #142, fixes #187); een issue die hij niet noemt, krijgt geen reactie.

FAQ

Hoeveel formulering is het waard om te bewaren per samengevoegd verzoek, een citaat of een volledige ticketlink? Een kort citaat is meestal genoeg voor het gangbare geval, omdat het doel ervan is een reviewer het bereik van formuleringen in één oogopslag te laten zien; bewaar ook de volledige ticketlink wanneer het origineel significante extra context had, zoals een screenshot of een gedetailleerde workflowbeschrijving die een citaat van één regel zou platslaan.

Maakt het bewaren van de formulering van elk duplicaat de backlog moeilijker te scannen? Niet als het standaard is ingeklapt. De canonieke titel is wat een snelle reviewer ziet; de samengevoegde formulering is één klik of één uitklap verwijderd, aanwezig voor wie dieper onderzoek doet maar zonder de weergave te overladen voor iemand die alleen stemmen telt.

Wat als twee verzoeken identiek lijken maar eenmaal gebouwd verschillende dingen blijken te willen? Splits ze weer op zodra dat duidelijk wordt, en behandel de originele samenvoeging als een redelijke beslissing genomen met de destijds beschikbare informatie, niet als een fout die herhaling moet vermijden. Een groeperingssysteem dat nooit iets ontkoppelt, zal uiteindelijk een paar verkeerde samenvoegingen permanent ingebakken hebben.

Is er een stemdrempel waarboven een samengevoegd verzoek een menselijke review van de onderliggende formulering zou moeten krijgen? Geen vast getal, maar elk verzoek dat een bouwbeslissing nadert verdient dit ongeacht het stemaantal, omdat dat het punt is waarop het verschil tussen "export" en "export als CSV met opgeslagen filters" ophoudt een nuance te zijn en de specificatie wordt.

GraphQL-deprecatie zonder versienummer

Thu, 17 Sep 2026 00:00:00 GMT

Een REST-API kan /v2/ naast /v1/ uitrollen en aanroepers op hun eigen tempo laten migreren. GraphQL heeft één schema op één endpoint, en elke client, de mobiele app op de build van vorig jaar en het interne dashboard dat vanochtend is uitgerold, bevraagt dezelfde graph. Er is geen URL om te forken. Een veld deprecaten betekent het ter plekke als gedeprecieerd markeren, in een schema waar iedereen al van afhangt, wat de discipline anders maakt dan REST, ook al is het onderliggende probleem, aanroepers vertellen dat iets gaat verdwijnen, hetzelfde als wat API-deprecatie in het algemeen behandelt.

Hoe markeert GraphQL een veld als gedeprecieerd, als er geen versie is om te verhogen?

Met de @deprecated-directive, toegepast direct op het veld:

type Product {
  price: Float @deprecated(reason: "Use priceV2 for multi-currency support.")
  priceV2: Money
}

Het veld blijft bevraagbaar. Het verdwijnt niet, geeft geen 404, verandert niet van gedrag; het draagt alleen een machineleesbare notitie die de meeste GraphQL-tools, GraphiQL, Apollo Studio, schema-linters, tonen aan iedereen die het schema doorbladert of er een query tegen schrijft. Dat is het hele mechanisme. Er is geen apart deprecatie-endpoint, geen header, geen bijbehorend document dat de spec vereist, wat zowel de aantrekkingskracht als de valkuil is: de directive is makkelijk toe te voegen en makkelijk te negeren, omdat niets een client dwingt ernaar te kijken.

Ziet iemand de deprecatiereden eigenlijk wel?

Alleen wie het schema rechtstreeks gebruikt, via introspectie of een schemabewuste editor, en dat is een kleiner publiek dan de gebruikelijke lezers van een API-changelog. Een mobiele app die zes maanden geleden tegen een query is gebouwd, heeft die query al ingebakken in zijn binary; hij blijft price opvragen en blijft een antwoord krijgen, gedeprecieerd of niet, totdat iemand de app opnieuw bouwt met het nieuwe veld en een update uitrolt. De directive zegt tegen een developer die nieuwe code schrijft dat ze het oude veld niet moet gebruiken. Het doet niets voor de client die al is uitgerold en draait.

Mechanisme	Wie het bereikt
`@deprecated`-directive	Developers die het schema doorbladeren of nieuwe queries schrijven
CI-fouten van schema-linter	Het team dat de clientcodebase bezit, als ze er een draaien
Een changelog-item	Wie het ook leest, inclusief een clientteam zonder linter
Niets (het veld werkt gewoon)	Een al gebouwde client die het oude veld gebruikt

Zou een gedeprecieerd veld toch een changelog-item moeten krijgen?

Ja, en dat doet meer werk dan de directive alleen, omdat een changelog mensen bereikt die de directive niet bereikt: een partnerteam dat de graph consumeert zonder het schema te doorbladeren, een client gebouwd tegen een maanden oude gecachte kopie van het schema, iedereen die het alleen zou opmerken door proza te lezen. API-changelog behandelt in het algemeen wat een item een aanroeper schuldig is; een GraphQL-item is één ding schuldig dat REST zelden hoeft te expliciteren, omdat REST-aanroepers dat afleiden uit het versienummer: of het oude veld vandaag nog werkt, nog werkt met een waarschuwing, of daadwerkelijk gestopt is met data teruggeven. De directive alleen beantwoordt daar niets van voor een lezer die het schema nooit heeft geopend.

Wanneer is het echt veilig om een veld uit het schema te verwijderen?

Alleen zodra querylogs laten zien dat niemand er meer om vraagt, wat een gebruiksvraag is, geen kalendervraag. Een veld kan een jaar @deprecated dragen en toch dragend zijn voor een client die nooit opnieuw is gebouwd; het op een vaste kalender verwijderen, zoals een REST-Sunset-header vaak doet, breekt die client zonder enige waarschuwing waarop hij kan reageren, omdat GraphQL hem niets geeft om op te reageren behalve de directive die hij nooit las. Log het gebruik op veldniveau voordat jullie je vastleggen op een verwijderdatum, en behandel elk niet-nul querytelling als een pauzeknop, geen aftelling.

Draagt het toevoegen van een veld hetzelfde risico als in een REST-API?

Minder, voor een nieuw veld, omdat een GraphQL-client alleen de velden ontvangt waar hij expliciet om vraagt. priceV2 naast price toevoegen kan een bestaande query niet breken op de manier waarop een veld toevoegen aan een REST-JSON-respons een strikte deserializer kan breken, omdat niets de client dwingt het nieuwe veld op te vragen. Een waarde toevoegen aan een bestaande enum is de uitzondering die het waard is in dezelfde adem te noemen: een client die exhaustief schakelt op elke enum-waarde, wat sterk getypeerde talen aanmoedigen, breekt zodra er een nieuwe waarde verschijnt, ongeacht of enige query erom vroeg. De veiligheid geldt alleen voor velden en union-leden waar een client zelf voor kiest; ze geldt niet voor een gesloten verzameling die de code van een client met de hand opsomt.

Wat heeft een GraphQL-changelog-item nodig dat een REST-item niet heeft?

De vorm van de query, niet alleen de veldnaam, omdat "het veld price is gedeprecieerd" precies het stuk mist dat een aanroeper echt nodig heeft: welke types en welke queries het raken. Een nuttig item noemt het type, het veld, het vervangende veld en, als jullie het kunnen genereren, de daadwerkelijke queries in productie die nog steeds de oude vorm opvragen. Dat laatste stuk, de deprecatiemelding koppelen aan echt gebruik, is wat REST-aanroepers gratis krijgen uit serverlogs op een URL en GraphQL-aanroepers niet, omdat elke query hetzelfde endpoint raakt, ongeacht wat hij opvraagt.

Kan iets anders dan een veld de `@deprecated`-directive dragen?

Enum-waarden, met dezelfde directive op de definitie van de waarde zelf in plaats van op het veld:

enum ShippingMethod {
  STANDARD
  EXPRESS
  OVERNIGHT @deprecated(reason: "Use EXPRESS with priority: true instead.")
}

De spec definieert @deprecated voor precies twee plekken, een velddefinitie of een enum-waarde, en verder niets in de stabiele release; deprecatie op argument- en input-veldniveau bestaat alleen in latere concepttaal, niet in wat de meeste servers vandaag implementeren. Een enum-waarde die zo is gemarkeerd, blijft een geldige waarde die een server nog kan teruggeven of accepteren, dezelfde niet-brekende belofte die een gedeprecieerd veld doet, wat het veilig maakt om uit te brengen voordat de waarde echt wordt verwijderd.

FAQ

Ondersteunt GraphQL iets als een Sunset-header voor een heel endpoint? Nee, omdat er meestal maar één endpoint is. De deprecatietiming leeft op veldniveau, in de redentekst van de @deprecated-directive en in welke changelog of migratiegids een team er ook naast publiceert, niet in een responseheader die een client programmatisch kan lezen.

Kan een gedeprecieerd veld worden verwijderd en later opnieuw worden toegevoegd met een ander type? Alleen als nieuwe veldnaam. Dezelfde veldnaam opnieuw introduceren met een veranderd type is precies de breaking change die de deprecatiecyclus probeert te voorkomen; geef de vervanging zijn eigen naam, zoals priceV2 doet, en laat de oude volledig uitsterven voordat de naam weer vrij is voor hergebruik.

Zou de @deprecated-redentekst moeten linken naar het changelog-item? Ja, wanneer de schematooling dat ondersteunt. Het redenveld accepteert een gewone string, en een URL binnen die string is de kortste weg van een developer die naar introspectie-output staart naar de vollere uitleg die een changelog-item kan geven.

Is een GraphQL-schemawijziging ooit backward compatible op een manier waarop REST dat niet is? Additieve veldwijzigingen, ja, om de reden hierboven: clients krijgen alleen wat ze opvragen. Nieuwe enum-waarden zijn de uitzondering, omdat een client die een gesloten verzameling opsomt kan breken op een waarde die hij niet verwachtte. Verwijderingen en typewijzigingen zijn precies zo breaking als hun REST-equivalenten.

Hoe je een API-migratiegids schrijft

Mon, 07 Sep 2026 00:00:00 GMT

Een API-migratiegids is het document dat van een breaking change een checklist maakt in plaats van een storing: wat er veranderde, wat je eraan doet, en tegen wanneer. Een changelog-regel kan een breaking change in twee zinnen noemen; een migratiegids is wat een aanroeper echt opent wanneer die twee zinnen zeggen "dit breekt jou" en ze precies moeten weten wat te wijzigen. De regel publiceren zonder de gids is hoe een aanroeper over een breaking change hoort via een supportticket in plaats van via het document dat geschreven is om dat te voorkomen.

Wat is een API-migratiegids?

Een stap-voor-stap document dat een aanroeper van de oude vorm van een API naar de nieuwe brengt, geschreven voor iemand met code om te wijzigen, niet voor iemand die nog beslist of de API wordt gebruikt. Dat onderscheid telt: een migratiegids gaat uit van een bestaande integratie en bestaand productieverkeer, dus moet hij rollback, gedeeltelijke migratie, en hoe je weet of de migratie lukte behandelen, niets daarvan hoeft een gids voor een eerste integratie te dekken.

Document	Gaat uit van	Beantwoordt
Migratiegids	Een bestaande integratie	Hoe kom ik van de oude naar de nieuwe vorm?
Changelog-regel	Niets, alleen dat de lezer checkt	Wat veranderde er, en wanneer?
API-referentie	Niets, of een eerste integratie	Wat doet dit endpoint?
Deprecation-melding	Een integratie die het oude gebruikt	Wanneer stopt dit met werken?

Een migratiegids staat meestal tussen de laatste twee in: een deprecation-melding start een klok, en de migratiegids is wat een aanroeper volgt voordat die klok afloopt.

Wanneer heeft een verandering een migratiegids nodig, en niet alleen een changelog-regel?

Wanneer er meer dan één stap zit tussen het oude en het nieuwe gedrag, of wanneer de verandering genoeg aanroeppunten raakt dat een aanroeper meer heeft aan een uitgewerkt voorbeeld dan aan een beschrijving. Wat is een breaking change, en hoe breng je die uit behandelt de test of een verandering breaking is; is het antwoord ja, dan is de tweede vraag of de fix een wijziging van één regel is of een echte migratie. Een hernoemd veld kan een aanroeper alleen met de changelog-regel afhandelen. Een verandering in authenticatie, paginering of foutafhandeling verdient bijna altijd een gids, omdat de juiste vervangende code niet vanzelf spreekt uit een zin lange beschrijving.

Wat moet een migratiegids bevatten?

Vijf dingen, en een ervan overslaan is hoe een gids een pagina wordt die een aanroeper één keer leest en dan terugvalt op vallen en opstaan. De oude code, getoond zoals die echt in een project zou verschijnen. De nieuwe code, op dezelfde manier getoond, niet als abstracte beschrijving van het verschil. Wat er breekt als er niets verandert, duidelijk gezegd, want "niets" is een geldig en gewoon antwoord dat een aanroeper toch expliciet moet horen. Een manier om te verifiëren dat de migratie werkte, zoals een responsveld of een statuscode om te checken. En een tijdlijn: wanneer het oude gedrag stopt met werken, en of beide vormen ondertussen beschikbaar zijn.

## Munteenheidvelden migreren van float naar integer (v3.0.0)

Voor:
  { "amount": 19.99 }

Na:
  { "amount": 1999 }  // kleinste munteenheid (centen)

Wat verandert: `amount` is nu een geheel getal in de kleinste
eenheid van de accountvaluta. Code die `amount` als float leest,
leest vanaf 1 oktober 2026 een 100x te grote waarde.

Verifiëren: na migratie moet een bedrag van $19,99 gelezen worden als
`amount: 1999`, niet als `amount: 19.99`.

Tijdlijn: v2 blijft floats teruggeven tot 15 januari 2027. v3 geeft
gehele getallen terug vanaf lancering. Beide versies zijn nu live.

Elk van die vijf dingen beantwoordt een vraag die een aanroeper anders zou moeten gokken of aan support moeten stellen, en dat is precies de kost die een migratiegids bespaart.

Wie zou hem moeten schrijven, en wanneer?

Wie de verandering ontwierp, op het moment dat die uitkomt, niet een supportteam dat hem later uit tickets reconstrueert. Wie de beslissing nam weet op welke delen van het oude gedrag niemand had moeten vertrouwen en welke een toevallig contract waren; een gids die later door iemand zonder die context wordt geschreven, legt het voor de hand liggende te veel uit of mist juist het ene randgeval dat mensen echt breekt. De gids en de changelog-regel die de breaking change aankondigt zouden samen moeten verschijnen, waarbij de regel naar de gids linkt in plaats van hem te herhalen.

Hoe verhoudt dit zich tot versionering en de API-changelog?

Direct: een migratiegids is de gedetailleerde versie van wat een MAJOR-regel in semantic versioning en je changelog slechts in één zin samenvat. De changelog-regel zegt dat een verandering breaking is en ruwweg wat er veranderde; de migratiegids is de link die die regel zou moeten dragen. API-changelog: wat te publiceren en wie het leest noemt de migratiegids als een van vijf documenten die een API onderhoudt, elk beantwoordt een andere vraag; dit is degene die "hoe kom ik echt van A naar B" beantwoordt, en verdient zijn eigen pagina juist omdat dat antwoord meestal te lang is voor een changelog-regel.

Hoe lang zou een migratiegids gepubliceerd moeten blijven?

Minstens zolang het oude gedrag bereikbaar is, en idealiter ook daarna. Een aanroeper die achttien maanden te laat migreert, na drie deprecation-meldingen te hebben genegeerd, heeft de gids nog steeds nodig, en hem verwijderen op de dag dat het oude gedrag wordt uitgeschakeld garandeert alleen dat de aanroeper die hem het hardst nodig heeft hem niet vindt. Houd hem op een stabiele URL en werk de tijdlijnsectie bij in plaats van de pagina in te trekken. De eigen upgradegids van Stripe is een publiek voorbeeld van dit patroon: één pagina, release na release actueel gehouden, in plaats van een nieuw document per versie dat verouderd raakt zodra de volgende verschijnt. Jullie eigen gids hoort ergens even vindbaar, naast de docs die een aanroeper toch al leest, in plaats van begraven in een blogarchief.

FAQ

Heeft elke breaking change een migratiegids nodig? Nee. Een verandering die een aanroeper alleen met de changelog-regel kan oplossen, zoals een enkel hernoemd veld met een voor de hand liggende vervanging, heeft geen aparte gids nodig. Een verandering die meerdere aanroeppunten raakt of een uitgewerkt voorbeeld nodig heeft, wel.

Hoort een migratiegids bij de API-documentatie of in de changelog? Bij de documentatie, gelinkt vanuit de changelog-regel. De regel is wat een abonnee eerst ziet; de gids is wat ze nodig heeft zodra ze besluit te handelen, en hoort naast het referentiemateriaal dat een aanroeper al gebruikt.

Wat is het verschil tussen een migratiegids en een deprecation-melding? Een deprecation-melding zegt dat iets gaat verdwijnen en tegen wanneer. Een migratiegids zijn de instructies over wat daaraan te doen. Een deprecation-melding zonder gelinkte migratiegids geeft een aanroeper een deadline zonder te zeggen hoe die te halen.

Moeten oud en nieuw gedrag beide gedocumenteerd zijn tijdens een migratievenster? Ja, indien mogelijk op dezelfde pagina, zodat een aanroeper precies ziet wat er veranderde in plaats van het samen te stellen uit twee aparte documenten die op verschillende momenten zijn geschreven.

Een changelog-check voor GitHub Actions

Mon, 07 Sep 2026 00:00:00 GMT

Elk team dat een changelog met de hand bijhoudt heeft na hetzelfde incident hetzelfde gesprek gehad: een release ging uit zonder item, iemand vraagt waarom, en het eerlijke antwoord is dat de persoon die het geschreven zou hebben snel bezig was en de changelog-stap alleen in het geheugen leefde. Changelog-automatisering behandelt wat een pipeline veilig kan automatiseren en wat nog een persoon nodig heeft; een changelog-check in CI is de andere helft van dat probleem, omdat het automatiseren van het schrijven niet helpt als niemand verplicht is het überhaupt te triggeren. GitHub Actions is waar de meeste teams hun pull-requestchecks al draaien, dus daar hoort deze ook thuis.

Waarom faalt "we vragen mensen een item toe te voegen" volgens een voorspelbaar patroon?

Omdat het in een pull request concurreert om aandacht met al het andere, en het het enige onderdeel is zonder directe consequentie bij overslaan. Tests falen luid en blokkeren de merge. Een ontbrekend changelog-item blokkeert niets, dus het verliest zodra iemand haast heeft, wat in de praktijk meestal is. Een beleid dat door geheugen wordt afgedwongen, verslechtert precies in het te verwachten tempo: prima de eerste paar weken nadat iedereen ermee instemt, dan stilletjes losgelaten zodra de persoon die het belangrijk vond op vakantie gaat of van team wisselt.

Wat verifieert een CI-check voor een changelog-item eigenlijk?

Niet de kwaliteit van de tekst, alleen of er een item bestaat en of het goed gevormd is, wat de juiste scope is voor een changelog-check die in CI draait in plaats van in iemands hoofd. Een gangbare vorm: de check kijkt naar de diff van de PR en vereist ofwel een nieuw bestand in een changeset-directory (het patroon dat Changesets en vergelijkbare tools gebruiken) of een gewijzigde regel in een changelog-bestand, en laat de build falen als geen van beide bestaat. De beoordeling van wat het item echt zegt gebeurt nog steeds waar het altijd gebeurde, in code review, omdat dat oordeel niet in een script thuishoort.

Wat de CI-check verifieert	Wat hij niet verifieert
Er staat een changeset of changelog-regel in de diff	Of de formulering duidelijk is
Het item verwijst naar het juiste pakket, in een monorepo	Of de wijziging überhaupt een item verdient
Het bestand is syntactisch geldig (frontmatter, JSON-vorm)	Of het item eerlijk is over de impact

Heeft elke PR er een nodig, of zijn sommige wijzigingen uitgezonderd?

Sommige zijn uitgezonderd, en de uitzonderingslijst is waar deze systemen echt gebouwd of losgelaten worden. Een dependency-bump zonder zichtbaar effect, een wijziging die alleen tests raakt, een interne refactor zonder gedragswijziging: geen van deze zou een bijdrager moeten dwingen een changelog-item te verzinnen voor iets waar niemand die de changelog leest om geeft. Het werkende patroon is een label of vlag die een bijdrager kan toepassen (no-changelog-needed) en die de CI-check zonder bestand tevredenstelt, beoordeeld door wie de PR goedkeurt, zodat de uitzondering zelf dezelfde controle doorloopt die een item zou doorlopen.

Wat gebeurt er met legitieme uitzonderingen, zoals een dringende hotfix?

De gate hoort bij de merge, niet bij de deploy: een hotfix onder echte tijdsdruk kan mergen met een placeholder-item of een vervolgticket, mits de CI-check tevreden is met intentie in plaats van alleen een afgerond stuk tekst; sommige teams accepteren een stub van één regel die een maintainer bijschaaft voor de volgende release-snit. Wat de gate nooit zou moeten toestaan is de stap stilletjes overslaan, want een stub die vergeten wordt is een kleiner falen dan een item dat nooit heeft bestaan, en een stub laat op zijn minst een spoor achter dat iemand later kan vinden.

# .github/workflows/changelog-check.yml
on:
  pull_request:
    types: [opened, synchronize, reopened, labeled, unlabeled]
jobs:
  changelog:
    if: >-
      !contains(github.event.pull_request.labels.*.name,
      'no-changelog-needed')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0 # de diff heeft de basisbranch nodig
      - name: Require changelog entry
        run: |
          base="origin/${{ github.base_ref }}"
          if ! git diff --name-only "$base"...HEAD \
              | grep -q '^\.changeset/'; then
            echo "No changeset. Add one, or have a maintainer"
            echo "apply the no-changelog-needed label."
            exit 1
          fi

Hoe weet je dat de check zelf klopt voordat hij echte PR's gaat blokkeren?

Open eerst een proef-pull request tegen een wegwerpbranch: één met een changeset, één zonder, en één met het uitzonderingslabel, en bevestig dat alle drie de verwachte uitkomst krijgen voordat de check op ieders werk wordt toegepast. Een changelog-check die fail-open gaat, elke PR laat slagen omdat een voorwaarde achterstevoren is geschreven, is erger dan geen check, omdat het eruitziet als dekking die er niet is. workflow_dispatch op hetzelfde bestand, handmatig uitgevoerd tegen een paar recent gemergde PR's, vangt de meeste van deze fouten zonder dat er een echte pull request voor nodig is.

Werkt hetzelfde idee ook buiten GitHub Actions?

De vorm blijft hetzelfde, alleen de syntax verandert. GitLab CI drukt dezelfde regel uit als een job-rules-blok dat $CI_MERGE_REQUEST_LABELS controleert in plaats van een GitHub Actions if, en een verplichte goedkeuring van de merge request kan de rol van de uitzonderingsbeoordeling overnemen. De check die dit artikel beschrijft is GitHub Actions omdat dat het platform is waar de meeste lezers al op zitten, maar de onderliggende eis, een machinaal gecontroleerde gate in plaats van een gevraagde afspraak, is overal hetzelfde waar CI vóór een merge draait.

Werkt dit hetzelfde in een monorepo?

Er is één stuk extra nodig: voor welk pakket het item is. Monorepo-changelogs behandelt waarom één repobreed bestand stopt te werken zodra pakketten onafhankelijk worden uitgebracht; de CI-check erft diezelfde eis; een changeset die geen pakket noemt is geen nuttig bewijs dat de juiste changelog zal bijwerken, alleen dat er ergens in de diff een bestand is veranderd. Tools die hiervoor gebouwd zijn (Changesets is de gangbare in het JavaScript-ecosysteem) vragen de bijdrager het betrokken pakket en een semver-bump te kiezen op hetzelfde moment dat de changeset wordt aangemaakt, zodat de CI-check beide stukken gratis krijgt in plaats van ze later af te leiden.

FAQ

Moet de CI-check de merge blokkeren, of alleen waarschuwen? Blokkeren. Een waarschuwing is functioneel identiek aan vriendelijk vragen, wat al gefaald heeft. Het uitzonderingslabel bestaat precies zodat een oprecht alleen-waarschuwen-geval toch een legitiem pad door dezelfde harde gate heeft.

Wie beoordeelt of een uitzonderingslabel correct is toegepast? Wie de pull request goedkeurt, als onderdeel van de beoordeling die diegene toch al doet. Het label zou nooit zelf toegepast en onbeoordeeld moeten blijven, anders wordt het dezelfde stille omweg die de gate juist moest sluiten.

Vervangt dit afdwingen in CI de behoefte aan een changelog-automatiseringspipeline? Nee, het voedt er een. Changelog-automatisering behandelt hoe gestructureerde items een pagina, een feed en een e-mail worden; de CI-check garandeert dat die gestructureerde items er überhaupt zijn om te automatiseren.

Wat is de kleinste versie hiervan die het waard is om eerst te bouwen? Eén enkele check die faalt als er geen bestand veranderd is onder een aangewezen changelog-directory, met één uitzonderingslabel. Pakketroutering en semver-afleiding voor een monorepo kunnen later komen; de kerngewoonte, een item bestaat of iemand heeft expliciet gezegd dat het niet nodig is, is wat het waard is om vanaf dag één te hebben.

Featureverzoek afwijzen zonder de klant te verliezen

Mon, 07 Sep 2026 00:00:00 GMT

De cirkel sluiten betekent meestal iemand vertellen dat hun verzoek is uitgekomen. De moeilijke helft, waarvoor de meeste bijhoudsystemen helemaal geen proces hebben, is nee zeggen. De meeste featureverzoeken komen nooit uit, wat betekent dat het grootste deel van de cirkel die een product echt aan zijn gebruikers verschuldigd is een afwijzing is, geen aankondiging, en een slecht gebrachte afwijzing kost meer goodwill dan stilte had gekost. Goed gebracht kan het bijna niets kosten, omdat wat degene die vraagt meestal het meest wil, is weten dat ze gehoord werd, niet de feature zelf.

Waarom telt goed afwijzen net zo zwaar als goed uitbrengen?

Omdat stilte leest als afwijzing zonder uitleg, en een uitgelegde nee leest als aandacht. Wie niets hoort neemt aan dat het verzoek genegeerd is of kwijtgeraakt, en beide conclusies leren haar te stoppen met de moeite nemen om te vragen, wat hetzelfde resultaat is dat een product krijgt bij een echte afwijzing, alleen langzamer bereikt en met meer wrok onderweg. Een reactie die duidelijk en met een reden nee zegt, sluit de cirkel net zo volledig als een uitgebrachte feature, en doet dat sneller.

Reactie	Wat de vrager leert	Kosten voor de relatie
Stilte	Niemand las het, of het kan niemand schelen	Hoog, en stapelt op met elk toekomstig verzoek
Automatisch antwoord zonder reden	Staat ergens onbeperkt in de wachtrij	Gemiddeld; koopt tijd maar geen vertrouwen
Afwijzing met reden	Is gelezen, overwogen en beantwoord	Laag, als de reden eerlijk is
Afwijzing met alternatief	De onderliggende behoefte is echt gehoord	Het laagst; bouwt vaak vertrouwen op

Wat laat een afwijzing slecht landen?

Bijna altijd drie dingen, gecombineerd. Genericiteit: een kant-en-klaar "bedankt voor je feedback" dat niet verwijst naar wat er echt gevraagd werd, leest alsof het helemaal niet gelezen is, ook al was dat wel zo. Vertraging: een afwijzing die zes maanden na het verzoek komt, als de vrager al vergeten is dat ze vroeg, voelt erger dan een snel nee, omdat het impliceert dat het verzoek onaangeroerd bleef liggen in plaats van overwogen en afgewezen te zijn. En een reden die geen stand houdt: "niet op onze roadmap" beantwoordt niets, terwijl "dit zou vereisen dat we herontwerpen hoe rechten werken, wat we dit jaar niet van plan zijn aan te pakken" de vrager iets geeft dat ze echt kan beoordelen en, als het genoeg uitmaakt, kan escaleren of omzeilen.

Wat zou een goede afwijzing echt moeten zeggen?

Vier dingen, in deze volgorde: een erkenning die het specifieke verzoek noemt, geen generieke parafrase; de echte reden, eerlijk gesteld zelfs als de eerlijke reden "dit past niet bij waar het product heen gaat" is in plaats van een zachtere smoes; of de deur dicht is of gewoon nu niet open, want dat vraagt om heel andere tonen; en, wanneer die er is, een alternatief dat de onderliggende behoefte aanpakt ook al is het niet de letterlijk gevraagde feature.

Hoi Jamie,

Bedankt voor het verzoek om bulk-CSV-import voor teamuitnodigingen toe
te voegen. We hebben het bekeken, en we gaan het niet bouwen: onze
uitnodigingsflow is gebouwd rond individuele beoordeling van elk nieuw
lid om veiligheidsredenen, en bulkimport zou daar tegenin gaan, niet
per ongeluk maar met opzet.

Als het echte pijnpunt is snel een groot team uitnodigen, ondersteunt
de API gescripte individuele uitnodigingen, wat je bijna alle snelheid
geeft zonder de beoordeling te omzeilen: [link]. Laat het weten als je
hulp wilt om dat op te zetten.

Merk op wat dit doet dat een template niet kan: het noemt de echte feature, geeft een reden gekoppeld aan een echte ontwerpbeslissing in plaats van een vaag beleid, en biedt een pad dat het onderliggende probleem oplost in plaats van alleen het ticket te sluiten.

Hoe verschilt dit van de cirkel sluiten bij een uitgebrachte feature?

De mechanica is vergelijkbaar, de toon niet. De feedbackloop met de klant sluiten behandelt het uitgebrachte geval, waar het bericht goed nieuws is en het grootste risico is vergeten het te sturen. Een afwijzing is slecht nieuws, of op zijn minst niet-gewenst nieuws, en vraagt om meer zorg in de gegeven reden en minder automatisering in de levering: een melding van een uitgebrachte feature kan een kant-en-klare reactie zijn getriggerd door een statuswijziging, maar een afwijzing die als kant-en-klaar leest is precies het faalgedrag dat deze hele aanpak wil vermijden. De twee delen wel één vereiste: het oorspronkelijke verzoek moet gekoppeld blijven aan wie het deed, dezelfde bijhouddiscipline die featureverzoeken bijhouden behandelt, anders is er geen manier om een van beide berichten individueel te versturen.

Zou een afwijzing publiek moeten zijn, zoals een status op een publieke roadmap?

Meestal niet de specifieke reden, ook al is de status dat wel. Publieke roadmap behandelt statuslabels die een vrager kan checken zonder opnieuw te vragen, en een "afgewezen" of "niet gepland" status kan deel uitmaken van dat systeem. Maar de gedetailleerde reden, vooral als die interne prioriteiten of weinig vleiende context raakt, is meestal meer waard in het individuele antwoord dan op een publieke statuspagina, waar dezelfde formulering moet werken voor elke lezer in plaats van voor de ene persoon die echt vroeg.

Verdient elk afgewezen verzoek een individuele reactie?

Elk verzoek van een genoemde, bereikbare persoon wel, al is het maar kort. Verzoeken met hoog volume, duplicaten of anonieme verzoeken zijn de uitzondering: vergelijkbare verzoeken groeperen en één keer per groep antwoorden, of een gedeeld statuslabel bijwerken, is redelijk wanneer individuele reacties echt niet schalen. De grens om te bewaken is dat "we kunnen niet iedereen individueel antwoorden" een echte operationele beperking moet zijn, gecheckt tegen het werkelijke volume, geen standaardexcuus om een antwoord over te slaan dat twee minuten had gekost.

FAQ

Is het beter snel af te wijzen met een zwakke reden, of tijd te nemen voor een goede? Snel, met een eerlijke reden, wint van beide apart. Een snel antwoord met een echte reden, al is die kort, presteert beter dan een langzaam antwoord met een gepolijste; de vertraging zelf is onderdeel van wat het vertrouwen schaadt.

Zou een afwijzing ooit moeten beloven het verzoek later te heroverwegen? Alleen als dat echt waarschijnlijk is en er een mechanisme is om het echt te heroverwegen, zoals een label dat het verzoek laat terugkomen bij een planningscyclus. Een vaag "we houden het in gedachten" zonder zo'n mechanisme is functioneel hetzelfde als stilte, alleen vriendelijker verwoord.

Wat als de eerlijke reden iets is dat het bedrijf niet kan delen, zoals een concurrentiezorg? Zeg dat direct in plaats van een zachtere reden te verzinnen. "We kunnen de specifieke redenering hier niet delen, maar dit is niet iets dat we van plan zijn te bouwen" is eerlijker, en wordt meer gerespecteerd, dan een verzonnen uitleg die instort bij een vervolgvraag.

Betekent een verzoek afwijzen dat het uit het bijhouden verwijderd moet worden? Nee. Bewaar het, gelabeld als afgewezen met de reden, zodat het deel uitmaakt van het patroon waartegen het volgende vergelijkbare verzoek wordt gegroepeerd, en zodat een later veranderde context (een nieuwe integratie, een nieuwe teamprioriteit) het weer kan laten terugkomen in plaats van de beoordeling helemaal opnieuw te beginnen.

Feature flag release notes: wat je zegt, en wanneer

Mon, 07 Sep 2026 00:00:00 GMT

De loop sluiten op een featureverzoek veronderstelt een duidelijk moment waarop het ding werd uitgebracht. Een feature flag haalt dat moment weg, en precies daardoor is de timing van feature flag release notes lastig. De code wordt gemerged, de flag bestaat, en dagen of weken daarna is de feature tegelijk live in productie en onzichtbaar voor bijna iedereen die hem zou willen gebruiken, vaak inclusief degene die er oorspronkelijk om vroeg. Te vroeg inlichten laat iemand tegen een feature aanlopen die er nog niet is. Te laat inlichten zorgt ervoor dat de loop die vertrouwen zou moeten opbouwen in plaats daarvan overkomt als vergeten.

Waarom breekt een flag de gebruikelijke volgorde "uitbrengen, inlichten"?

Omdat het één gebeurtenis splitst in minstens twee: de code die live gaat, en de flag die wordt aangezet voor een bepaald account. Elk proces om een feedbackloop te sluiten veronderstelt dat die twee samen gebeuren, wat waar is voor de meeste releases en onwaar voor alles achter een flag die gebruikt wordt voor gefaseerde uitrol, targeting of als noodschakelaar. De klant-feedbackloop sluiten beschrijft het inlichten van de aanvrager op het precieze moment dat een changelog-entry wordt goedgekeurd en gepubliceerd; die stap is geschreven voor het geval waarin het publiceren van de entry en de feature bruikbaar worden hetzelfde moment zijn, en een flag is precies het geval waarin dat niet zo is.

Moment	Wat waar is	Moet de aanvrager al ingelicht worden
Code gemerged, flag overal uit	Feature bestaat, niemand kan hem gebruiken	Nee
Flag aan voor het account van de aanvrager	Feature bestaat, die persoon specifiek kan hem gebruiken	Ja
Flag aan voor een uitrolpercentage dat hen uitsluit	Feature bestaat, die persoon kan hem nog steeds niet gebruiken	Nee
Flag helemaal verwijderd, feature staat gewoon aan	Feature bestaat voor iedereen	Ja, als nog niet ingelicht

Wat is de echte regel voor wanneer je iemand inlicht?

Licht in wanneer de flag aan staat voor hun account, niet wanneer de code wordt gemerged en niet wanneer de flag wordt aangemaakt. Die ene regel dekt elke rij in de tabel hierboven, omdat hij de melding koppelt aan het enige feit dat er voor de aanvrager echt toe doet: kan hij, op dit moment, het ding gaan gebruiken. Een melding gekoppeld aan de merge of het aanmaken van de flag is eigenlijk een voortgangsrapport over engineering, en wie een feature aanvroeg wil geen voortgangsrapport, die wil weten wanneer te gaan kijken.

Betekent dat dat de aanvrager vroege of speciale toegang nodig heeft?

Niet per se, en het afdwingen creëert zijn eigen probleem. Als de flag geleidelijk wordt uitgerold om redenen van belasting of stabiliteit, ondermijnt het vooraan de wachtrij zetten van één account alleen om een loop sneller te sluiten de reden waarom de uitrol gefaseerd is. De eerlijke opties zijn: wachten tot het account van de aanvrager de uitrol op natuurlijke wijze bereikt en dan inlichten, of, als de urgentie het rechtvaardigt, hen bewust vroeg de flag geven, als een echte beslissing van wie de uitrol bezit, niet als bijeffect van de wens een melding te versturen.

Wat als de flag een noodschakelaar is, geen uitrolmechanisme?

Dan draait de veilige aanname om. Een flag bedoeld om een feature snel te kunnen uitschakelen, in plaats van de release ervan te faseren, betekent meestal dat de feature volledig live hoort te zijn zodra hij wordt aangemaakt, en de flag bestaat voor veiligheid in plaats van volgorde. In dat geval is de aanvrager inlichten op het moment van deploy correct, net als bij elke release zonder flag; het bestaan van de flag is een operationeel detail dat niet zou moeten veranderen wanneer de loop sluit. Het onderscheid dat ertoe doet is waarvoor de flag dient, niet of er een bestaat.

Verandert de flag wat feature flag release notes zouden moeten zeggen?

Het verandert wanneer de entry wordt gepubliceerd, niet wat hij bevat. Een entry gepubliceerd op het precieze moment dat de flag aan staat voor 100% van de accounts, leest exact als een normale changelog-entry, en dat hoort ook zo; een lezer die hem later vindt heeft geen reden om te weten dat er ooit een flag bij betrokken was. Wat het niet zou moeten doen, is publiceren terwijl de flag slechts aan staat voor een klein uitrolpercentage, omdat een publieke changelog-entry iedereen die hem leest, inclusief accounts zonder de flag, op zoek stuurt naar een feature die ze niet zullen vinden, wat een ergere versie van hetzelfde probleem is, op productbrede schaal in plaats van op de schaal van één aanvrager. Die timingregel is het hele verschil tussen feature flag release notes en een gewone entry: de inhoud is hetzelfde, alleen de publicatiedatum verschuift. Release notes schrijven behandelt de discipline van "geen actie nodig" die ook hier geldt: lezers moeten weten of dit hen betreft, niet alleen dat het ergens bestaat.

Zouden product-update-e-mails een geflagde feature anders moeten behandelen?

Ja, vooral door uit te stellen in plaats van te herschrijven. De product-update-e-mailtemplate behandelt gerichte notificaties tegenover brede digests; een geflagde feature is een geval waarin de timing van een gerichte notificatie gecontroleerd moet worden tegen de eigen flagstatus van de ontvanger voordat hij verstuurd wordt, iets wat een brede digest helemaal niet gemakkelijk kan, wat nog een reden is waarom een digest het verkeerde kanaal is voor alles dat nog midden in de uitrol zit.

FAQ

Moet je een aanvrager vertellen dat hun feature "eraan komt" zodra de flag bestaat maar nog niet aan staat voor hen? Alleen als er een echte, nabije datum aan vasthangt, en zelfs dan spaarzaam. Een "eraan komt" zonder datum leest, na genoeg tijd, hetzelfde als stilte, en creëert een tweede belofte die ook bijgehouden en nagekomen moet worden.

Wie beslist wanneer een flag ver genoeg staat om de loop te sluiten? Wie de uitrol bezit, niet wie de notificatie bezit. Wie de uitrol heeft weet of "100% van de accounts" nabij is of nog weken weg; de sluitstap koppelen aan hun status, in plaats van aan een vaste kalenderdatum, houdt de melding eerlijk.

Krijgt een feature achter een permanente flag (nooit helemaal verwijderd) ooit een publieke changelog-entry? Ja, zodra hij bereikt wat "algemeen beschikbaar" ook betekent voor dat product, zelfs als de flag zelf om operationele redenen voor altijd in de code blijft. De changelog-entry gaat over beschikbaarheid voor de lezer, niet over het implementatiedetail van hoe die beschikbaarheid tot stand komt.

Wat als de flag verwijderd wordt en de feature gedood wordt in plaats van uitgebracht? Dat is een afwijzing, geen uitbrengmelding, en verdient dezelfde zorg als elke andere afwijzing. Hoe je een featureverzoek afwijst behandelt wat dat bericht zou moeten zeggen; de loop eerlijk sluiten betekent soms hem sluiten met een nee.

Hebben feature flag release notes een apart template nodig ten opzichte van een gewone entry? Geen templatewijziging, alleen een controlestap vóór publicatie: check de flagstatus voor het account dat vroeg, niet alleen dat de code is gemerged, en houd de entry vast tot die check slaagt. Al het andere aan de entry, de formulering, de lengte, de FAQ-discipline, blijft hetzelfde als bij elke andere release note.

Featureverzoeken bijhouden zonder ze kwijt te raken

Mon, 07 Sep 2026 00:00:00 GMT

Het bijhouden van featureverzoeken faalt bijna altijd op een van twee manieren. Ofwel hebben verzoeken geen plek om heen te gaan, dus leven ze in inboxen en Slack-threads waar ze een voor een vergeten worden, ofwel hebben ze een plek die niemand meer bekijkt, dus worden ze allemaal samen vergeten. Een werkend systeem moet beide storingen overleven: het heeft één plek nodig waar elk verzoek terechtkomt, en een reden om die plek volgende maand weer te openen.

Waar komen featureverzoeken eigenlijk vandaan?

Uit meer kanalen dan de meeste bijhoudsystemen voorzien. Een supportticket met een "zou fijn zijn als". Een reactie op een publieke roadmap. Een salesgesprek waarin een prospect precies het ene ding noemt dat de deal blokkeert. Een widget in het product. Elk kanaal heeft een eigen eigenaar en eigen tools, en juist daarom verspreiden verzoeken zich: de supportticketrij en de backlog van het productteam zijn zelden hetzelfde systeem, en een verzoek dat maar een van de twee bereikt, heeft in de praktijk maar één afdeling bereikt.

Bron	Typische eigenaar	Waar het meestal doodloopt
Supporttickets	Supportteam	Gesloten als opgelost, nooit meer bekeken
Salesgesprekken	Sales / accountmanagement	Een CRM-veld dat niemand in product leest
Widget in het product	Product	Een formulier zonder follow-up
Reacties op de roadmap	Wie de roadmap ook bouwde	De reactiethread zelf
Social media / reviews	Marketing of niemand	Eén keer een screenshot van gemaakt, dan weg

Eén intakeformulier voor elk kanaal werkt niet, omdat niemand het gebruikt. Wat wel werkt is één bestemming waar elk kanaal naartoe leidt, ook al is de routing eerst vijf minuten per dag kopiëren en plakken totdat het geautomatiseerd is.

Wat breekt het bijhouden van featureverzoeken echt?

Bijna altijd twee dingen. Ten eerste een ontbrekende bestemming: verzoeken worden beantwoord in het kanaal waar ze binnenkwamen en nooit ergens duurzaam vastgelegd, waardoor hetzelfde verzoek van drie verschillende klanten eruitziet als drie losstaande, ongerelateerde antwoorden in plaats van één signaal. Ten tweede, vaker, een bestemming die volloopt en niet meer gelezen wordt. Een spreadsheet met 400 rijen zonder filter is geen bijhoudsysteem meer; het is een archief dat toevallig beschrijfbaar is.

De tweede storing is de gevaarlijkste, omdat het lijkt alsof bijhouden werkt. Verzoeken worden geregistreerd. Niets lijkt kapot totdat iemand vraagt "hoeveel mensen hebben om X gevraagd" en het eerlijke antwoord is "we zouden alle 400 rijen moeten lezen om het te weten".

Wat moet een featureverzoek eigenlijk vastleggen?

Genoeg om later drie vragen te beantwoorden zonder het oorspronkelijke bericht opnieuw te lezen: wat er gevraagd werd, waar mogelijk in de eigen woorden van de aanvrager; wie het vroeg, en hoe diegene te bereiken als het antwoord uiteindelijk "we hebben het gebouwd" is; en wat er nodig is om te weten of dit een gangbaar verzoek is of een eenmalig geval. Een letterlijk citaat telt meer dan een parafrase, omdat een parafrase geschreven door wie het verzoek ook trieerde al zijn eigen interpretatie meedraagt, en dat is precies wat een tweede lezer zes maanden later niet meer kan controleren.

Welke labels zijn de moeite waard?

Twee, en ze beantwoorden verschillende vragen. Een type-label scheidt een featureverzoek van een bugreport, omdat beide een andere eigenaar en tijdlijn nodig hebben, en ze mengen in één rij laat de luidste klachten voor de verzoeken dringen. Een prioriteit-label, beperkt tot een kleine set als low, medium en high, scheidt "blokkeert iemand in het gebruik van het product" van "zou leuk zijn", omdat beide een heel andere reactietijd verdienen en geen van beide het tempo van de ander zou moeten overnemen. Het type-label goed zetten veronderstelt dat het verzoek is wat het beweert te zijn; wanneer een featureverzoek eigenlijk een bugreport is behandelt het geval waarin de eigen woorden van een klant dat label de verkeerde kant op sturen.

Geautomatiseerde triage kan beide toepassen op het moment dat een verzoek binnenkomt. Bij changeloop krijgt een widget-inzending in dezelfde stap het label feature-request of bug en een priority:low|medium|high-label, plus een from-widget-tag zodat de bron zichtbaar is zonder het item te openen. Dat is genoeg om de backlog in een minuut in plaats van een middag te filteren: laat me elk hoge-prioriteitsverzoek zien dat deze maand via de widget binnenkwam.

Een derde label is de moeite waard zodra er een publieke roadmap is: een status die een aanvrager zelf kan checken. Publieke roadmap behandelt de statussen planned, building en shipped volledig; kort gezegd verandert dat label een privérij in iets dat een aanvrager kan raadplegen zonder opnieuw te vragen.

Hoe beslis je wat je hierna bouwt?

Eerst groeperen, dan tellen. Tien verschillend geformuleerde verzoeken voor dezelfde onderliggende capaciteit lezen als tien verspreide rijen in een spreadsheet, en als een sterk signaal zodra ze gegroepeerd zijn, en die groepering is meestal de ontbrekende stap, niet het tellen. Een ruw aantal zonder groepering beloont meestal de feature met de meest pakkende naam, niet die met de meeste echte vraag erachter.

Weeg naar wie het vraagt, niet alleen naar hoeveel er vragen. Een verzoek van een account dat bijna verlengt draagt een andere urgentie dan hetzelfde verzoek van een trialaccount, en een bijhoudsysteem dat die context weggooit voor een kale telling optimaliseert voor het cijfer dat het makkelijkst te berekenen is, niet het nuttigste.

Elke beslissing hier produceert ook verzoeken die verliezen, en die verdienen ook een reactie; hoe je een featureverzoek afwijst behandelt wat je zegt tegen wie een verzoek deed dat het niet haalde. Groeperen en wegen is maar de helft van "wat bouwen we hierna"; featureverzoeken prioriteren behandelt de echte frameworks, RICE, omzetweging en ruwe tellingen, en waar elk breekt.

Hoe sluit je de cirkel als er iets uitkomt?

Dit is de stap die bijhoudsystemen het vaakst overslaan, en degene die aanvragers echt opmerken. De feedbackloop met de klant sluiten behandelt de mechaniek volledig; wat hier hoort, is dat de cirkel sluiten alleen werkt als het oorspronkelijke verzoek gekoppeld bleef aan de aanvrager. Een featureverzoek-template gebouwd vanuit een GitHub-issue, waarbij de identiteit van de aanvrager aan de issue hangt in plaats van begraven in een reactie, is wat een automatische "uitgebracht"-melding mogelijk maakt in plaats van een die iemand moet onthouden te sturen. Featureverzoek-template toont het concrete template en waar elk veld voor dient.

FAQ

Welke tool moet ik gebruiken om featureverzoeken bij te houden? Wat het team al dagelijks bekijkt, verslaat elke speciale tool die niemand opent. Een GitHub-issuetracker werkt goed als engineering daar al leeft; een lichtgewicht bord werkt goed als product daar leeft. De tool doet er minder toe dan of hij wordt teruggeopend.

Hoe voorkom ik dat featureverzoeken dubbel worden? Groepeer op onderliggende capaciteit voordat je op formulering trieert. Zoeken in bestaande verzoeken voordat je een nieuwe aanmaakt, vangt de meeste duplicaten; een maandelijkse groeperingsronde vangt de rest. Duplicaten samenvoegen zonder de originele stem te verliezen behandelt wat je met de formulering doet zodra het groeperen zelf klaar is, zodat de samenvoeging het verzoek niet stilletjes versmalt tot wat de eerst binnengekomen indiening toevallig vroeg.

Moet elk featureverzoek een reactie krijgen? Elk verzoek moet een bevestiging krijgen, al is die kort, maar niet elk verzoek heeft direct een beslissing nodig. Een zichtbare status, zoals een roadmap-label dat de aanvrager zelf kan checken, vervangt de meeste individuele reacties die een team anders zou moeten geven.

Wat is het verschil tussen het bijhouden van verzoeken en een publieke roadmap? Bijhouden is het interne overzicht van elk verzoek, inclusief degene die nooit uitkomen. Een publieke roadmap is de subset waar een team zich publiekelijk aan committeert, met een status die de aanvrager kan zien zonder opnieuw te vragen.

Wanneer een featureverzoek eigenlijk een bugreport is

Mon, 07 Sep 2026 00:00:00 GMT

"Kunnen jullie een instelling toevoegen om de exportlimiet te verhogen?" leest als een featureverzoek, en de meeste triagesystemen labelen het meteen zo. Soms is het dat ook. Soms faalt de export bij een getal onder de gedocumenteerde limiet door een bug, en de klant, die de code niet kan zien, heeft de meest plausibele oplossing verzonnen die ze kan beschrijven: geef me een groter getal en misschien werkt het dan. Welke labels zijn de moeite waard behandelt het type-label dat een backlog verdeelt in featureverzoeken en bugs; dit is het geval waarin de eigen woorden van een klant het label de verkeerde kant op sturen, en de kosten van het fout krijgen zijn een langzame drift naar een backlog vol wensen die niemand echt wil zodra je eronder kijkt.

Hoe ziet een featureverzoek eruit dat eigenlijk een bug is?

Het noemt een workaround in plaats van het probleem. Een echt featureverzoek beschrijft meestal een resultaat dat het product helemaal niet ondersteunt: "laat me dit voor later plannen", "voeg een donkere modus toe". Een verkeerd geclassificeerde bug beschrijft een specifiek getal, drempel of gedrag dat klinkt als een ontbrekende instelling maar eigenlijk een symptoom is: "verhoog de timeout", "voeg een retry-optie toe", "laat me meer rijen tegelijk exporteren". Het kenmerk is dat de aanvrager een implementatie voorstelt, een instelling, een schakelaar, een override, in plaats van een doel te beschrijven, omdat ze de feature al heeft geprobeerd zoals gedocumenteerd en het deed niet wat de documentatie zegt dat het zou moeten doen.

Signaal	Featureverzoek	Bug vermomd als featureverzoek
Wat de aanvrager beschrijft	Een resultaat dat het product niet kan	Een parameter die ze wil veranderen
Of gedocumenteerd gedrag dit al dekt	Nee, echt ontbrekend	Ja, maar werkt niet zoals gedocumenteerd
Of meer inspanning het verzoek doet verdwijnen	Nee	Soms, als de bug drempelafhankelijk is
Waar het naartoe zou moeten	Productbacklog	Bugrij

Waarom is dit belangrijker dan het klinkt?

Omdat de twee rijen verschillende eigenaren, tijdlijnen en succescriteria hebben, en een bug die als featureverzoek is ingediend wordt geprioriteerd tegen featureverzoeken, wat om aandacht concurreert met echte producthiaten in plaats van opgelost te worden op de tijdlijn die een bug verdient. Featureverzoeken bijhouden behandelt waarom het mengen van bugs en features in één rij de luidste klachten voor de echte verzoeken laat dringen; een featureverzoek dat stiekem een bug is, richt de omgekeerde schade aan, blijft in de productbacklog stemmen verzamelen voor een "feature" die zou verdwijnen zodra de onderliggende bug is opgelost, wat het prioriteringssignaal verspilt voor iedereen die die backlog leest.

Hoe onderscheid je het als de eigen woorden van de klant de verkeerde kant op wijzen?

Vraag wat ze verwachtte dat er zou gebeuren, niet wat ze wil dat je toevoegt. "De export liep vast op 500 rijen en ik heb er 2.000 nodig, kunnen jullie de limiet verhogen" klinkt als een featureverzoek voor limietverhoging totdat de vervolgvraag, "is 500 de gedocumenteerde limiet", onthult dat het gedocumenteerde getal 5.000 was en de export vroegtijdig faalt. Die ene vraag, wat ze verwachtte tegenover wat er gebeurde, doet het meeste sorteerwerk, omdat een echt featureverzoek geen gedocumenteerd gedrag heeft waar het bij achterblijft; er is niets te verwachten omdat de mogelijkheid nog niet bestaat.

Moeten supportmedewerkers of engineers dit beslissen?

Supportmedewerkers doen de eerste ronde, omdat zij het ticket het eerst zien, maar het label zou makkelijk te veranderen en goedkoop om fout te doen moeten zijn, geen eenmalige beslissing die het item voor altijd in de verkeerde rij vastzet. Een lichte tweede controle, een engineer die wekelijks nieuwe "featureverzoek"-labels doorneemt op alles dat naar een verborgen bug ruikt, vangt de gevallen die een supportmedewerker zonder codebase-context niet had kunnen herkennen. Dit hoeft niet formeel te zijn; het is meer een blik van vijf minuten dan een reviewproces.

Verandert het sluiten van de lus zodra de echte bug is gevonden?

Ja, en het verbetert het bericht dat je kunt sturen. De klantfeedbacklus sluiten behandelt het informeren van een aanvrager wanneer hun wens uitkomt; een geherclassificeerde bug krijgt een betere versie van dat bericht, omdat "we hebben de bug erachter gevonden en opgelost" klinkt als competentie, terwijl "we hebben de feature gebouwd waar je om vroeg" alleen bij toeval waar zou zijn geweest, omdat het echte featureverzoek, een daadwerkelijk hogere exportlimiet, misschien nooit gebouwd wordt zodra de bug weg is en de oorspronkelijke limiet van 5.000 rijen genoeg is.

Wat gebeurt er als de verkeerde classificatie nooit wordt opgemerkt?

De backlog vult zich met wensen die op echte vraag lijken en dat niet zijn, en prioriteringsbeslissingen die tegen die backlog worden genomen erven de vertekening. Een "feature" met veertig stemmen kan in werkelijkheid veertig mensen zijn die dezelfde bug tegenkomen, en het letterlijke verzoek bouwen, een instelling om een limiet te verhogen die nooit echt de beperking was, levert complexiteit die niets oplost, terwijl de onderliggende bug doorgaat met nieuwe "featureverzoeken" genereren van klanten die dit topic nog niet hebben gevonden.

FAQ

Is het de moeite waard om een formele stap toe te voegen om elk featureverzoek tegen bekende bugs te checken? Geen formele stap, meer een gewoonte: wie een nieuw featureverzoek triageert zou moeten vragen "beweert het gedocumenteerde gedrag al dit te doen" voordat het label wordt toegepast, omdat die ene vraag de meeste verkeerde classificaties vangt zonder procesoverhead toe te voegen.

Wat als de klant blijft volhouden dat het een featureverzoek is, ook nadat de bug is gevonden? Leg uit wat je hebt gevonden en waarom de instelling die ze voorstelde niet meer nodig zou zijn zodra de bug is opgelost. De meeste klanten vragen om een workaround omdat ze aannamen dat de echte oplossing niet beschikbaar was, niet omdat ze specifiek die instelling wilden.

Verliest een geherclassificeerd item de stemmen of reacties die het als featureverzoek verzamelde? Het zou ze zichtbaar moeten behouden, omdat die stemmen het bewijs zijn dat tot het vinden van de bug heeft geleid, en dat spoor verbergen maakt dezelfde verkeerde classificatie de volgende keer, op een ander ticket, moeilijker te herkennen.

Kan dit ook andersom gebeuren, een bugreport dat eigenlijk een featureverzoek is? Minder vaak, maar ja: "dit is kapot" betekent soms "dit doet niet wat ik aannam dat het zou doen", wat een ontbrekende mogelijkheid is, geen defect. Dezelfde vraag, wat ze verwachtte tegenover wat gedocumenteerd is, sorteert ook in deze richting.

Supporttickets vs. featureverzoeken: wat vertrouw je?

Mon, 07 Sep 2026 00:00:00 GMT

Een featureverzoekbord vangt wat gebruikers vragen wanneer ze tijd hebben om te gaan zitten en te beschrijven wat ze willen. Een supportticket vangt waar gebruikers nu op vastlopen, vaak geïrriteerd, vaak zonder het vocabulaire om het onderliggende verzoek netjes te beschrijven. Beide zijn echte signalen, en teams die maar naar één van de twee kijken, lossen uiteindelijk met zelfvertrouwen het verkeerde probleem op, omdat elk kanaal systematisch een ander soort gebruiker en een ander soort behoefte oververtegenwoordigt. Featureverzoeken prioriteren behandelt het rangschikken van wat al op het bord staat; dit gaat over het gat tussen wat het bord überhaupt bereikt en wat alleen ooit als supportticket verschijnt.

Waarom zou hetzelfde onderliggende probleem in het ene kanaal verschijnen en niet in het andere?

Omdat de twee kanalen verschillende activatiekosten hebben, en de grootte van die kosten bepaalt wie ze overwint. Een featureverzoek indienen vereist initiatief: een gebruiker moet geloven dat het verzoek de moeite waard is om te verwoorden, het bord vinden, en iets samenhangends schrijven, wat betrokken, geduldige gebruikers selecteert die al in het product hebben geïnvesteerd. Een supportticket indienen vereist in vergelijking bijna geen initiatief, vaak gewoon een klik op "help" midden in een taak, wat betekent dat het gefrustreerde gebruikers op het moment zelf vangt, inclusief degenen die zich nooit met een featureverzoekbord zouden bemoeien. Een echt gat in het product kan onzichtbaar zijn op het featurebord en luidruchtig in support simpelweg omdat de gebruikers die het raken, degenen zijn die het minst geneigd zijn een formeel verzoek in te dienen.

Betekent ticketvolume voor een ontbrekende feature hetzelfde als stemmenaantal ervoor?

Nee, omdat ze verschillende populaties meten onder verschillende omstandigheden. Een featureverzoek met honderd stemmen vertegenwoordigt honderd mensen die de tijd namen om een bestaand verzoek te vinden en te steunen, wat een sterk signaal is van duurzame, overwogen vraag. Honderd supporttickets over hetzelfde onderliggende gat, ingediend in dezelfde periode, vertegenwoordigen waarschijnlijk gebruikers die op het moment tegen een muur aanlopen, van wie sommigen het volledig zouden vergeten zodra de directe frictie voorbij is. Beide behandelen als gelijkwaardig "honderd mensen willen dit"-signaal overweegt het ticketvolume te zwaar, omdat tickets goedkoop zijn om te genereren en stemmen niet.

Featureverzoekbord	Supporttickets
Vereist initiatief om in te dienen	Vereist bijna geen
Vangt overwogen, duurzame vraag	Vangt frustratie op het moment
Neigt naar betrokken, geduldige gebruikers	Vangt gebruikers die het bord nooit zouden gebruiken
Een stemmenaantal is een echt commitmentsignaal	Een ticketaantal weerspiegelt frictie, niet altijd wens

Wat betekent het als een feature supporttickets heeft maar bijna geen stemmen op het bord?

Vaak dat het verzoek bestaat maar de gebruikers die het raken niet weten dat het bord bestaat, niet geloven dat stemmen iets uithaalt, of het probleem te zelden tegenkomen om de moeite te nemen van kanaal te wisselen om het formeel te registreren. Dit is precies de populatie die een featureverzoekbord structureel mist, en een laag stemmenaantal hier is bewijs van een meetgat, niet van lage vraag. Behandel een cluster supporttickets rond een ontbrekende feature als een eigen signaal dat het waard is om zelf, namens de gebruikers, op het bord te loggen, in plaats van de tickets te wantrouwen, zodat het niet onzichtbaar blijft voor wie prioriteert op basis van alleen stemmenaantallen.

Bord leest als lage prioriteit:
"Export to CSV": 4 stemmen in 6 maanden

Support vertelt een ander verhaal:
"Export to CSV": 31 tickets in dezelfde periode, elk van
een ander account, elk gesloten met "momenteel niet
ondersteund, we geven de feedback door"

Betekent een piek in supporttickets altijd dat het onderliggende probleem een ontbrekende feature is?

Nee, en hier kunnen de twee kanalen in de tegenovergestelde richting misleiden. Een tickpiek wordt net zo vaak veroorzaakt door een verwarrende interface rond een al bestaande feature, een bug, of een verandering die zonder voldoende uitleg uitkwam, waarvan geen enkele wordt opgelost door iets nieuws te bouwen. Elke tickpiek lezen als "gebruikers willen een feature die we niet hebben" produceert een roadmap vol dingen die eigenlijk documentatiegaten of vermomde bruikbaarheidsproblemen waren. Het supportticket vertelt je waar de frictie zit; het vertelt je op zichzelf niet of de oplossing een nieuwe feature, een interfaceverandering, of een beter hulpartikel is, en dat door elkaar halen verspilt engineeringtijd aan de verkeerde oplossing.

Hoe zouden de twee signalen echt gecombineerd moeten worden bij het beslissen wat te bouwen?

Gebruik tickets om te vinden waar de frictie zit, en gebruik het featureverzoekbord, plus directe outreach waar het bord dun is, om te bevestigen hoe het werkelijk gewenste resultaat eruitziet. Een tickcluster identificeert een echt, gevoeld probleem; het specificeert zelden de oplossing precies genoeg om ertegen te bouwen, omdat een gefrustreerde gebruiker in een supportgesprek symptomen beschrijft, geen specificaties. Het featureverzoekbord, wanneer het genoeg stemmen heeft op hetzelfde onderliggende probleem, draagt doorgaans meer van het detail van "wat zou dit werkelijk bevredigen", omdat het schrijven van een verzoek al een daad is van specificeren wat je wilt, niet alleen rapporteren wat er mis is.

Zouden supportagenten tickets zelf als featureverzoeken moeten loggen?

Ja, en dit is de enkele fix met de meeste hefboomwerking voor het gat tussen de twee kanalen. Een agent die een ticket herkent als een vermomd featureverzoek, in plaats van het gewoon op te lossen en verder te gaan, kan het namens de klant op het bord loggen, wat het meetgat direct dicht in plaats van te vereisen dat de klant een tweede kanaal ontdekt en gebruikt. Dit werkt alleen als loggen voor de agent seconden kost, geen minuten, zodat de frictie van het doen ervan lager is dan de frictie van gewoon het ticket sluiten en verdergaan naar het volgende.

FAQ

Zouden featureverzoekstemmen ooit gekort moeten worden als ze allemaal van één account of team komen? Ja, weeg naar afzonderlijke accounts of organisaties in plaats van naar ruw stemmenaantal, omdat vijf stemmen van vijf mensen bij hetzelfde bedrijf de prioriteiten van één klant vertegenwoordigen, niet vijf onafhankelijke bevestigingen van vraag.

Is het de moeite waard om een feature te bouwen die zwaar in tickets voorkomt maar bijna geen stemmen heeft? Vaak wel, mits het ticketvolume echt van afzonderlijke accounts komt en de onderliggende behoefte bevestigd is in plaats van aangenomen; behandel het lage stemmenaantal als een meetartefact van de activatiekosten van het bord, niet als bewijs dat de vraag niet echt is.

Hoe onderscheid je op het eerste gezicht een UI-verwarringsticket van een echt ontbrekende-featureticket? Kijk of de oplossing bestaat uit het uitleggen van een bestaande mogelijkheid of het verontschuldigen voor een ontbrekende. Een patroon van "oh, het staat er eigenlijk gewoon"-oplossingen wijst op een interface- of vindbaarheidsprobleem; een patroon van "dat ondersteunen we nog niet" wijst op een echt gat.

Doet dit onderscheid er evenveel toe bij een heel klein supportvolume? Minder mechanisch, aangezien een handvol tickets makkelijk individueel te lezen is zonder geaggregeerde analyse nodig te hebben, maar de onderliggende bias, tickets oververtegenwoordigen gefrustreerde gebruikers en ondervertegenwoordigen geduldige, is aanwezig op elke schaal en het waard om in gedachten te houden zelfs wanneer je elk ticket zelf leest.

Git-tags, releases en je changelog

Mon, 07 Sep 2026 00:00:00 GMT

Een git-tag, een release en een changelog-regel zijn drie verschillende registraties van dezelfde gebeurtenis, en ze door elkaar halen laat een changelog stilletjes afdrijven van wat er echt is uitgebracht. Een tag markeert een commit. Een release verpakt die tag met artefacten en een beschrijving. Een changelog-regel legt uit, in termen die een lezer buiten de repository kan gebruiken, wat er veranderde. Ze gebeuren meestal dicht bij elkaar in tijd, en precies daarom is het makkelijk om ze als één stap te behandelen in plaats van drie, en precies daarom wordt de kloof pas maanden later zichtbaar, als iemand vraagt "wat kwam er uit in v2.4" en het eerlijke antwoord echt graafwerk vergt.

Wat is het echte verschil tussen de drie?

Registratie	Leeft in	Geschreven voor
Git-tag	De repository, als ref	Iedereen die exact die commit uitcheckt
Release	De codehost (GitHub, GitLab)	Iedereen die een build downloadt
Changelog-regel	De eigen changelog van het product	Iedereen die het product gebruikt, niet alleen de repo

Een tag is de meest mechanische van de drie: git tag v2.4.0 en klaar, zonder dat iets hoeft uit te leggen wat erin zit. Een release voegt een beschrijving toe en meestal downloadbare artefacten, en het publiek blijft ontwikkelaars die weten wat een releasepagina is. Een changelog-regel is de enige van de drie geschreven voor een lezer die de repository misschien nooit opent, waardoor het degene is die de meeste redactionele aandacht nodig heeft en het meest waarschijnlijk wordt overgeslagen onder deadlinedruk.

Heeft elke git-tag een changelog-regel nodig?

Nee, en ze één-op-één behandelen is een veelgemaakte fout. Een tag kan een interne mijlpaal markeren, een release candidate, of een hotfix die de meeste gebruikers nooit bereikt; geen van die hoeft per se een publieke regel. De test is dezelfde die bepaalt of iets überhaupt in een changelog hoort: zou een gebruiker of aanroeper dit merken of erom geven. De meeste tags halen die test. Sommige, zoals een tag die puur wordt gemaakt om een CI-pipeline te triggeren, nooit.

Heeft elke changelog-regel zijn eigen tag nodig?

Niet altijd, en hier lopen teams die continu deployen uiteen van teams die geversioneerde pakketten uitbrengen. Een SaaS-product dat meerdere keren per dag deployt kan meerdere deploys groeperen onder één gedateerde changelog-regel zonder 1:1-tag per deploy; een bibliotheek gepubliceerd in een pakketregister heeft meestal een tag per gepubliceerde versie nodig. Go-modules en Swift Package Manager resolven versies rechtstreeks uit de tags; op npm of PyPI bewaart het register de gepubliceerde versie, en de tag is hoe iedereen die versie terugkoppelt aan de broncode. Een repository met meerdere onafhankelijk geversioneerde packages moet dit per package beslissen, niet één keer voor de hele repo; monorepo-changelogs behandelt hoe tag-prefixen en changelog-scope zouden moeten volgen op packagegrenzen, niet op mapgrenzen. Semantic versioning en je changelog behandelt hoe het versienummer zelf zou moeten mappen op changelog-categorieën; tags zijn het mechanisme dat een versienummer controleerbaar maakt tegen de echte code.

Hoe moet een releasebeschrijving zich verhouden tot de changelog-regel?

Ze kunnen dezelfde tekst zijn, maar alleen als het publiek van beide echt hetzelfde is, wat zeldzamer is dan het lijkt. Een releasepagina op een codehost wordt bijna uitsluitend gelezen door ontwikkelaars; als een product ook niet-technische gebruikers heeft die de changelog lezen, stuurt het letterlijk dupliceren van de releasebeschrijving interne termen en codegerichte formulering naar een lezer die de gewone-taalversie nodig had. Het schoonste patroon: schrijf de changelog-regel als het primaire, lezersgerichte artefact, en laat de releasebeschrijving er ofwel naar linken, ofwel een kortere, technischere samenvatting houden voor het publiek dat daar al thuis is.

# Release v2.4.0 (GitHub, voor ontwikkelaars)
Verhoogt de rapportenpipeline naar de nieuwe aggregatie-engine. Zie
changelog voor de klantgerichte samenvatting:
https://example.com/changelog#v2.4.0

## 2026-09-07 (Changelog, klantgericht)
### Added
- Rapporten laden nu in minder dan een seconde, zelfs voor accounts
  met meer dan een miljoen rijen.

Dezelfde release, twee documenten, elk met zijn eigen formulering voor zijn eigen lezer.

Waar komt de changelog-regel eigenlijk vandaan?

Uit twee startpunten, en de meeste echte pipelines zijn een mix van beide. Hij kan gegenereerd worden uit commit-berichten op het moment van de tag, wat snel is en nooit een gemergde pull request mist; van conventional commits naar changelog behandelt die pipeline volledig. Of hij kan met de hand geschreven worden, los van de tag, getimed op het moment dat een feature als klaar wordt beschouwd in plaats van het moment dat code wordt gemergd. Gegenereerde regels zijn consistent maar erven elk vaag commit-bericht; met de hand geschreven regels zijn duidelijker maar hebben iemand nodig die ze echt schrijft. De meeste teams die automatiseren houden toch een lichte redactieslag aan op de gegenereerde tekst voordat die de publieke regel wordt, dezelfde discipline die Keep a Changelog, in de praktijk aanbeveelt, ongeacht waar de ruwe tekst oorspronkelijk vandaan kwam.

Wat breekt er als de drie uit sync raken?

Het vertrouwen in wat de lezer eerst checkte. Een tag die bestaat zonder bijbehorende changelog-regel lijkt, vanuit de kant van de changelog-lezer, alsof er die week niets is gebeurd. Een changelog-regel zonder bijbehorende tag of release maakt het onmogelijk voor iemand die een productieprobleem debugt om exact de code uit te checken die live was toen een regel werd gepubliceerd. De oplossing is geen perfecte automatisering, het is één bron van waarheid voor de koppeling: één plek, al is het maar de eigen checklist van het releaseproces, die zegt dat een uit te brengen verandering alle drie krijgt, in dezelfde commit of pull request die hem introduceert.

FAQ

Zouden changelog-regels automatisch gegenereerd moeten worden uit git-tags? Ze kunnen een startpunt zijn, maar een tag alleen draagt geen lezersgerichte beschrijving, alleen een commit-bereik. Geautomatiseerde generatie moet de commit-berichten binnen dat bereik lezen, niet alleen het bestaan van de tag, om iets bruikbaars te produceren.

Wat als we niet elke release taggen? Dan wordt de changelog-regel de primaire registratie, en die zou toch een datum moeten dragen en, als het product er een heeft, een versienummer, zodat de regel iets blijft waar een lezer later naar kan verwijzen, ook zonder bijbehorende tag.

Moeten pre-release-tags (zoals v2.4.0-rc.1) changelog-regels krijgen? Over het algemeen niet. Een release candidate is voor interne of bètatests, en een changelog-regel ervoor traint lezers om regels te verwachten voor versies die misschien nooit zo worden uitgebracht als beschreven. Bewaar regels voor tags die algemene beschikbaarheid bereiken.

Kan één changelog-regel meerdere git-tags dekken? Ja, en dat zou vaak moeten voor teams die frequent taggen. Groepeer gerelateerde tags onder één gedateerde regel die de netto verandering beschrijft, in plaats van per tag een dunne regel te publiceren die een feature over meerdere leesbeurten fragmenteert.

Interne API-changelogs: wat verandert er

Mon, 07 Sep 2026 00:00:00 GMT

Elk ander artikel in dit hub gaat ervan uit dat degene die een API aanroept buiten het bedrijf zit: de engineer van een klant, een partner, iemand die de docs zelf vond. Veel API's hebben een heel ander soort aanroeper, een team aan de andere kant van de gang of twee verdiepingen verderop, en dat verandert de afweging van wat een changelog hen verschuldigd is, omdat een Slack-bericht hen bereikt en er meestal nooit een supportticket wordt geopend. De meeste teams concluderen hieruit dat interne API's geen changelog nodig hebben. Wat ze echt nodig hebben, is een andere.

Wat maakt de changelog van een interne API anders dan die van een publieke?

Het publiek is rechtstreeks bereikbaar, wat de belangrijkste reden wegneemt waarom de meeste publieke API-changelogs bestaan: uitzenden naar aanroepers die je niet individueel kunt bereiken. Het team dat een interne API bezit, weet meestal precies welke andere teams hem aanroepen, soms tot op de specifieke service. Dat maakt een gericht bericht, geen publieke feed, de natuurlijke standaard, en daarom eindigen interne API's zo vaak zonder enige changelog: het eigenaarsteam waarschuwt de twee of drie teams die het zich herinnert, in de veronderstelling dat dat iedereen dekt.

	Publieke API-changelog	Interne API-changelog
Wie leest het	Elke externe aanroeper, meestal niet rechtstreeks bereikbaar	Een kleine, meestal bekende groep interne teams
Standaardkanaal	Een pagina en een feed	Een bericht aan de aanroepende teams, idealiter ook een pagina
Grootste risico	Een aanroeper mist de entry helemaal	Het eigenaarsteam vergeet een aanroeper waarvan het niet weet dat die bestaat
Wat "we weten niet wie ons aanroept" vervangt	Niets; breed publiceren	Een echt, actueel gehouden register van aanroepers

Waarom faalt "we lichten gewoon de teams in die ons aanroepen"?

Omdat de groep aanroepers nooit zo klein of zo statisch is als het eigenaarsteam zich herinnert. Een service gebouwd voor één consument krijgt zes maanden later een tweede aanroeper, via een integratie die niemand aankondigde, en de mentale lijst "wie roept ons aan" van het eigenaarsteam klopt nu niet meer zonder dat iemand het merkt. De fout is gewoon en veelvoorkomend, het standaardresultaat van vertrouwen op geheugen in plaats van op een register, geen teken dat iemand nalatig was. Wat is een breaking change behandelt hoe je beslist of een API-wijziging überhaupt als breaking telt; het interne geval voegt daar een tweede, moeilijkere vraag aan toe, namelijk weten wie je moet inlichten.

Heeft een interne API überhaupt een changelog-pagina in publieke stijl nodig?

Meestal wel, ook al is het primaire kanaal direct. Een pagina geeft het directe bericht iets om naar te linken, zodat de melding kort kan blijven ("breaking change in /v2/accounts, details hier") in plaats van te proberen de volledige uitleg in een chatbericht te proppen dat wegscrollt. Het wordt ook wat een nieuw team, of een team dat het directe bericht miste, kan checken wanneer hun integratie breekt en ze proberen te achterhalen waarom. De pagina hoeft niet gepolijst of publiek te zijn; hij moet linkbaar zijn en de Slack-thread overleven die hem aankondigde.

Wie onderhoudt eigenlijk de lijst van aanroepers?

Het eigenaarsteam, en dat moet behandeld worden als een echt artefact, niet als stamkennis. De goedkoopste versie is een bestand in de eigen repository van de API, een korte lijst van consumerende services met een eigenaar per item, bijgewerkt telkens wanneer een nieuwe integratie wordt gebouwd, dezelfde discipline als elke afhankelijkheidsverklaring. Het alternatief, rondvragen voor elke breaking change, werkt tot de ene keer dat iemand vergeet de juiste persoon te vragen, en een interne API die stilletjes breekt voor één team is een kleiner incident dan een publiek, maar het blijft een incident, meestal ontdekt door de eigen wachtdienst van dat team in plaats van door de eigenaar van de API.

# consumers.yml
- service: billing-service
  owner: "#team-billing"
  since: 2026-03-01
- service: reporting-pipeline
  owner: "#team-analytics"
  since: 2026-06-14

Zo'n bestand maakt van "wie moeten we inlichten" een opzoeking in plaats van een vraag. Tools die precies voor dit probleem zijn gebouwd, zoals Backstage's service catalog, modelleren API's als eersteklas entiteiten met vastgelegde consumenten om dezelfde reden: zodra een organisatie genoeg interne services heeft, blijft niemands geheugen van wie wat aanroept vanzelf accuraat, en moet iets anders het register bijhouden. De docs van welke tool je intern ook al draait, zijn meestal de juiste plek om te checken voordat je zelf iets bouwt.

Wat hoort in een interne changelog-entry die een publieke niet nodig zou hebben?

Meer operationele specificiteit, omdat de lezer een andere engineer is die hierop zal handelen binnen dezelfde infrastructuur, en het niet als samenvatting zal lezen. In welke omgevingen de wijziging live is en wanneer, omdat interne services vaak door stadia gepromoveerd worden die een publieke aanroeper nooit ziet. Of de wijziging een configuratie- of client-library-update aan de kant van de consument vereist, geformuleerd als een commando als die er is. En, omdat interne aanroepers de fix vaak rechtstreeks met het eigenaarsteam kunnen afstemmen, een met naam genoemd contact in plaats van een supportkanaal: "stuur @maria een bericht als dit iets breekt" is een volkomen redelijke regel in een interne entry en een vreemde in een publieke API-changelog.

Geldt dit op dezelfde manier voor een changelog binnen een monorepo?

Het verscherpt hetzelfde probleem in plaats van het te vervangen. Monorepo-changelogs behandelt wanneer een package zijn eigen changelog nodig heeft; een interne API die één van meerdere packages in een monorepo is, heeft zijn consumenten alsnog expliciet bijgehouden nodig, omdat dezelfde repository delen met wie hem aanroept niet betekent dat ze een wijziging opmerken tenzij iets hen erop wijst. Nabijheid in de repo is niet hetzelfde als nabijheid in aandacht.

FAQ

Heeft een puur interne API een changelog nodig als hij maar één aanroeper heeft? Nauwelijks, en een direct bericht aan dat ene team volstaat meestal. De changelog verdient zichzelf terug zodra er meer dan één aanroeper is, of zodra de lijst met aanroepers het eigenaarsteam ooit heeft verrast, want dat is het signaal dat geheugen alleen niet meer betrouwbaar is.

Zouden interne API-wijzigingen dezelfde review moeten doorlopen als publieke? De formulering mag lichter zijn, omdat de lezer een collega is en geen externe aanroeper, maar de beslissing of een wijziging breaking is verdient in beide gevallen dezelfde zorg. Een interne aanroeper heeft alsnog productiecode die van het oude gedrag afhangt.

Hoe kom je erachter wie een interne API aanroept als dat nooit is bijgehouden? Serverlogs of de verkeersdata van een service mesh zijn het eerlijke antwoord als er nooit een consumentenregister werd bijgehouden; behandel die ontdekking als het moment om er een te beginnen, niet als een eenmalige opruiming.

Is een Slack-bericht genoeg, of heeft een interne wijziging alsnog een formele changelog-entry nodig? Beide, voor alles dat niet puur additief is. Het bericht is wat op tijd gelezen wordt; de entry is wat een team dat weken later een probleem onderzoekt, en het bericht nooit zag, alsnog kan vinden.

Interne release notes: wie het nog meer moet weten

Mon, 07 Sep 2026 00:00:00 GMT

Elk ander artikel in dit hub gaat ervan uit dat de lezer van een release note een klant is. Support, sales en customer success lezen ook, of proberen het, en de meesten horen wat er uitkwam doordat een klant er eerst naar vraagt. Die volgorde is omgekeerd, en het is ook de standaard bij de meeste bedrijven, omdat het releaseproces eindigt op het moment dat de klantgerichte notitie uitgaat, en niemand een tweede, kleinere stap heeft gebouwd voor de mensen die een uur later vragen erover moeten beantwoorden.

Wat is een interne release note, en hoe verschilt die van een klantgerichte?

Het is een korter document, geschreven voor mensen die het product al door en door kennen, dat hun vertelt wat er is veranderd en wat ze daaraan moeten doen in hun concrete werk. Een supportmedewerker heeft niet de gepolijste framing nodig die een klantgerichte aankondiging gebruikt; die moet weten hoe de verandering er nu in het product uitziet, wat de meest waarschijnlijke vraag erover zal zijn, en of open tickets erdoor geraakt worden. Een klantgerichte notitie verkoopt de verandering. Een interne rust iemand uit om ermee om te gaan.

Publiek	Wat het moet weten	Waar het het nodig heeft
Support	Wat er in de UI veranderde, waarschijnlijke vragen, geraakte open tickets	Waar het al antwoorden opzoekt
Sales	Wat het ontgrendelt voor een deal, wat het nog niet doet	Waar het zich voorbereidt op gesprekken
Customer success	Wat te zeggen tegen bestaande klanten, en wie erom vroeg	Waar het outreach plant
Leiding	Wat er uitkwam versus wat beloofd was, en wanneer	Een korte, terugkerende samenvatting, niet per release

Waarom horen interne teams lanceringen te laat?

Omdat het releaseproces meestal is opgebouwd rond één artefact, de klantgerichte notitie of de changelog-regel, en aangenomen wordt dat al het interne volgt uit het lezen van dat ene document. Dat is niet zo. Supportmedewerkers zijn bezig met het ticket voor hun neus, niet met een changelog doorbladeren voor context, en een notitie geschreven voor een klant laat vaak precies het operationele detail weg dat een medewerker nodig heeft, zoals aan welk plan de feature is gekoppeld of hoe de foutmelding eruitziet als het misgaat. Tegen de tijd dat een klant ernaar vraagt, leest de medewerker dezelfde publieke notitie die de klant net las, zonder enige voorsprong.

Wat moet een interne release note zeggen dat een klantgerichte niet zegt?

De operationele details die een klantgerichte notitie bewust weglaat. Welke plannen of accounts het hebben. Hoe het eruitziet als iets misgaat, en wat te zeggen tegen een klant die dat tegenkomt. Of het openstaande verzoeken of tickets sluit, en welke, zodat een medewerker die aan een gerelateerd ticket werkt weet dat hij moet checken. Wie in het team verantwoordelijk is als een vraag verder gaat dan wat de notitie dekt. Niets hiervan hoort bij de klantgerichte versie, geschreven om één keer gelezen te worden door iemand buiten het bedrijf; dit alles is precies wat iemand nodig heeft die dezelfde vraag veertig keer per week beantwoordt.

Interne notitie: bulk-CSV-export (komt uit op 08-09-2026)

- Alleen voor Team- en Enterprise-plannen. Free en Pro zien geen
  verandering.
- Veelvoorkomende fout: exports boven 50k rijen lopen vast op
  een timeout; bekend probleem, fix apart bijgehouden. Klant
  vertellen om te filteren op datumbereik.
- Sluit 14 open verzoeken gelabeld `bulk-export`. Reactiesjabloon
  staat in het gedeelde document.
- Verantwoordelijk: platform-team, #platform-eng voor alles wat
  buiten deze notitie valt.

Vier regels die een supportmedewerker meteen kan gebruiken, waarvan geen enkele in de publieke changelog-regel voor dezelfde feature zou horen.

Wie moet het schrijven, en wanneer?

Wie de klantgerichte notitie schrijft is meestal de juiste persoon, omdat die al alle context heeft, maar het moet een aparte, korte pas zijn in plaats van een poging om één document beide publieken te laten bedienen. Ze samenvoegen levert of een klantgerichte notitie vol interne details op, of een interne notitie die te gepolijst is om echt nuttig te zijn, en in de praktijk gaat het sneller om twee korte documenten te schrijven dan om te onderhandelen over één document dat twee publieken tegelijk moet bedienen. Timing telt zwaarder dan auteurschap: de interne notitie moet uitkomen vóór de klantgerichte, al is het maar een paar uur eerder, zodat support nooit een verandering hoort op dezelfde plek als een klant.

Waar moet het leven zodat support het echt vindt op het moment van een ticket?

Waar het team al zoekt als er een ticket binnenkomt, niet in een aparte changelog die niemand uit zichzelf reden heeft te openen. Een supportteam dat een gedeelde kennisbank gebruikt heeft de notitie daar nodig, gelinkt vanaf waar tickets over dat deel van het product al gelabeld worden. Een team dat in een gedeeld kanaal leeft heeft het daar geplaatst nodig, doorzoekbaar, op het moment dat het relevant is, in plaats van begraven in een dagelijkse digest die ze één keer doorbladeren. Het klantgerichte patroon van gerichte notificatie versus digest geldt ook hier: een interne notitie over een specifieke, aanstaande verandering moet het team rechtstreeks bereiken, niet wachten op een wekelijkse samenvatting die aankomt nadat het eerste ticket al bestaat.

Heeft het dezelfde reviewstrengheid nodig als de externe?

Minder, en dat is bewust. Een klantgerichte notitie vertegenwoordigt het bedrijf publiekelijk en verdient een zorgvuldige redactiepas; een interne notitie bestaat om snel en concreet te zijn, en het aan dezelfde poleringsstandaard houden is meestal precies wat teams ertoe brengt om het helemaal niet meer te schrijven. Een snelle, wat ruwe interne notitie die een uur voor de lancering uitkomt verslaat een gepolijste die de dag erna aankomt, wanneer het eerste supportticket al verward is binnengekomen.

FAQ

Moeten interne release notes hetzelfde goedkeuringsproces doorlopen als klantgerichte? Nee. Een lichtere, snellere pas is precies het punt. Dezelfde review eisen maakt van een interne notitie van dezelfde dag er een van de week erna, tegen welke tijd support de vraag al zonder heeft beantwoord.

Wie is verantwoordelijk voor interne release notes als er geen aparte rol voor interne communicatie is? Wie de klantgerichte notitie schrijft, als een tweede, korte pas er meteen na. Er is geen aparte verantwoordelijke nodig, alleen de gewoonte om de klantgerichte notitie niet te behandelen als het enige artefact dat een release oplevert.

Hebben interne release notes een eigen changelog of archief nodig? Een doorzoekbare plek verslaat een chronologisch archief dat niemand doorscrollt. Als support al een kennisbank heeft, hoort de notitie daar, gelabeld aan de feature, in plaats van in een apart intern changelog dat alleen helpt wie de uitkomdatum al kent.

Wat is het risico van interne release notes overslaan bij kleine wijzigingen? Kleine wijzigingen zijn precies degene waarover support onaangekondigd vragen krijgt, omdat een kleine wijziging zelden een bedrijfsbrede aankondiging krijgt. De omvang van de release note moet schalen met de omvang van de wijziging; die mag nooit naar nul zakken alleen omdat de wijziging klein was.

Release notes voor mobiele apps: wat de limiet wegsnijdt

Mon, 07 Sep 2026 00:00:00 GMT

Alles in dit hub over release notes schrijven veronderstelt een pagina die je volledig controleert: elke lengte, links die werken, opmaak die rendert. De release notes van een mobiele app leven in de doos van iemand anders. Apple geeft ongeveer 4.000 tekens maar toont alleen de eerste paar regels voordat "meer" wordt getikt; Google geeft vergelijkbare ruimte met hetzelfde effectieve voorbeeldprobleem, en geen van beide platformen rendert een klikbare link in de tekst. De regels uit release notes schrijven die mensen echt lezen gelden nog steeds: zeg wat er veranderde en wat de lezer moet doen, maar de ruimte om dat te doen is een fractie van wat een changelog-pagina toelaat, en de keuzes moeten weloverwogen zijn, niet per ongeluk.

Wat past er eigenlijk in het zichtbare voorbeeld?

De eerste een of twee regels, ongeveer 80 tot 170 tekens afhankelijk van apparaat en lettergrootte, voordat een lezer moet tikken om uit te klappen. Dat is het hele budget voor het deel van de release note dat bepaalt of iemand de rest gaat lezen, en het betekent dat de belangrijkste zin eerst moet komen, niet het versienummer, geen begroeting, geen categoriekop. Een release note die begint met "Nieuw in deze versie:" heeft al een derde van zijn zichtbare ruimte besteed aan vier woorden die de lezer niets vertellen.

Platform	Ongeveer totale limiet	Effectief voorbeeld voor "meer"
App Store (iOS)	~4.000 tekens	2-3 regels, ongeveer 80-170 tekens
Google Play	~500 tekens per taal, sommige velden korter	2-3 regels, vergelijkbaar met iOS
Beide	Geen klikbare links in het release-notes-veld	N.v.t.

Werkt de regel "wat kun je nu, wat ben je verschuldigd" nog op deze lengte?

Ja, en hij wordt strenger, niet anders. Eén zin per entry, werkwoord eerst, geen inleiding: "Exporteer je gegevens als CSV vanuit Instellingen." wint van "We hebben de mogelijkheid toegevoegd voor gebruikers om nu hun gegevens in CSV-formaat te exporteren" door een derde van de woorden te gebruiken om hetzelfde te zeggen. Op de lengte van een changelog-pagina kost een wat breedsprakige zin een lezer een halve seconde. Op de lengte van een mobiele release note kan diezelfde breedsprakigheid de zin helemaal buiten het zichtbare voorbeeld duwen, zodat de lezer het werkwoord dat had verteld wat er veranderde nooit ziet.

Slecht, verspilt het voorbeeld aan de omlijsting:
"We zijn verheugd om je een nieuwe update vol
verbeteringen te brengen! Lees verder voor details."

Goed, alle waarde in de eerste regel:
"Exporteer je gegevens als CSV. Donkere modus volgt nu
de systeeminstelling. Crash bij openen van gedeelde
links verholpen."

Wat moet er weg dat een web-changelog-entry normaal zou behouden?

Links, eerst, omdat geen van beide stores ze klikbaar rendert, dus een URL in de tekst is dood gewicht dat een lezer zou moeten overtypen. Als de entry een bestemming nodig heeft, zeg dan in plaats daarvan wat er in de app getikt moet worden: "Zie de nieuwe filters onder Instellingen > Zoeken" werkt; "Lees meer op example.com/blog/filters" niet, op dit oppervlak. Ten tweede, alles wat voorwaardelijk of doelgroepspecifiek is: een web-changelog kan zeggen "als je de API gebruikt, raakt dit jou", maar een winkelvermelding bereikt elke geïnstalleerde gebruiker tegelijk, dus een voorwaardelijke regel leest als ruis voor de 95% waarop het niet van toepassing is. Zet het voorwaardelijke detail in plaats daarvan in een in-app-bericht, getriggerd voor de accounts die het echt betreft.

Moet elke release zijn eigen notes krijgen, of is het oké om "bugfixes en prestatieverbeteringen" te hergebruiken?

Hergebruik het voor releases die dat oprecht zijn, maar controleer hoe vaak dat echt waar is. Release notes schrijven behandelt al waarom die zin een note verraadt die van binnenuit is geschreven in plaats van voor de lezer; op mobiel richt het dubbele schade aan, omdat winkel-release-notes een van de weinige plekken zijn waar sommige gebruikers tussen updates door überhaupt iets zien, en een lange reeks "bugfixes en prestatieverbeteringen" leest alsof de app niet verandert, wat een slechtere indruk maakt dan helemaal geen notes voor die periode.

Beïnvloeden release notes of mensen de app überhaupt updaten?

Indirect, via zichtbaarheid in plaats van overtuiging. De meeste gebruikers updaten automatisch en lezen de notes nooit voor het updaten; de notes tellen het meest voor de minderheid die updates handmatig controleert, en voor recensenten of pers die de geschiedenis van een winkelvermelding doorbladeren. Schrijven voor dat kleinere publiek betaalt zich toch uit, omdat een vermelding met een echte geschiedenis van specifieke, gedateerde entries leest als een actief onderhouden app, en een vermelding met een jaar "bugfixes en prestatieverbeteringen" niet, ongeacht hoeveel er in die tijd echt werd uitgebracht.

En een geforceerde update, waarbij de note moet uitleggen waarom de gebruiker geen keuze heeft?

Vermeld de reden en de deadline in de eerste regel, voor al het andere, want een geforceerde update is het ene geval waarin de lezer al geïrriteerd is voordat hij begint te lezen. "Deze update is nodig om je gegevens te blijven synchroniseren. Update voor [datum] om onderbreking te voorkomen." zegt in één zin wat te doen en waarom; die reden begraven onder drie regels ongerelateerde featurenotes leest alsof de app het vervelende deel verbergt.

FAQ

Moeten mobiele release notes overeenkomen met de web-changelog van dezelfde release? Dezelfde onderliggende wijzigingen dekken, maar niet woord voor woord. De web-changelog kan zich de volledige uitleg veroorloven; de mobiele note heeft dezelfde feiten nodig, samengeperst tot een zin met het werkwoord eerst, wat meestal betekent dat het een herschrijving is, geen kopie.

Is het de moeite waard om mobiele release notes te lokaliseren voor elke ondersteunde taal? Ja, meer dan voor een web-changelog, omdat de winkelvermelding vaak het enige gelokaliseerde oppervlak is dat sommige gebruikers tussen sessies zien, en beide platformen ondersteunen release notes per locale zonder extra engineeringwerk buiten de vertaling zelf.

Hoe lang zou een mobiele release note moeten zijn als er geen limiet is die beknoptheid afdwingt? Kort sowieso. Het plafond van 4.000 tekens op iOS is zelden de echte beperking; dat is het voorbeeld van 2-3 regels, en schrijven voorbij wat dat voorbeeld toont, betekent alleen dat minder mensen het deel lezen dat ertoe deed.

Hebben release notes het versienummer nodig in de zichtbare tekst? Nee. De store toont het versienummer al naast de notes. Het herhalen in de tekst besteedt zichtbare tekens aan informatie die de lezer al voor zich heeft.

Monorepo-changelogs: één, of één per package?

Mon, 07 Sep 2026 00:00:00 GMT

Een monorepo huisvest meerdere apart uit te brengen dingen in één repository, en een changelog moet eerst een vraag beantwoorden: interesseert het de lezer om de repo, of om één specifiek package erin? De meeste teams beslissen dit nooit bewust. Ze beginnen met één changelog omdat er één repo is, voegen gaandeweg packages toe, en eindigen met een log waarin iemand die de CLI gebruikt langs veertig irrelevante backend-regels moet scrollen om die te vinden die zijn fix uitbracht. Wat de juiste vorm bepaalt, is niet de structuur van de repository, maar wie het log leest en wat die persoon al weet te zoeken.

Wat maakt de changelog van een monorepo anders dan die van een enkele repo?

Een changelog voor één repo heeft een impliciet publiek: iedereen die het enige gebruikt wat die repo bouwt. Het publiek van een monorepo splitst per package, en packages in dezelfde repo worden vaak op verschillende schema's uitgebracht, aan verschillende afnemers, op verschillende stabiliteitsniveaus. Een bibliotheek gepubliceerd in een register en een intern beheertool kunnen in dezelfde monorepo leven en voor de lezer van de changelog bijna niets gemeen hebben.

Repo-vorm	Typische lezer	Passende changelog
Eén uit te brengen app	Iedereen die het product gebruikt	Eén log, voor de hele repo
Bibliotheek-workspace (meerdere gepubliceerde packages)	Wie van een specifiek package afhangt	Eén log per package
App plus interne tools	Twee verschillende publieken zonder overlap	Gesplitst per publiek, niet per map
App plus eigen SDK	Productgebruikers, en SDK-integrators	Twee logs: productgericht en SDK-gericht

Heeft elk package zijn eigen changelog nodig?

Alleen die met een onafhankelijk publiek. Een package gepubliceerd in een register heeft zijn eigen log nodig, omdat wie het installeert geen reden heeft om iets anders in de repo te lezen, en releasetools voor monorepo's zoals Lerna en Changesets schrijven een CHANGELOG.md per package, naast de package.json. Een interne utility met één afnemer, de app die al in dezelfde repo leeft, heeft geen apart log nodig; de wijzigingen ervan opnemen in de regels van die app is nuttiger dan een tweede bestand dat niemand buiten het team opent.

De test is dezelfde die bepaalt of een willekeurige regel in een changelog thuishoort: zou de lezer het opmerken of erom geven, en kan die er iets mee doen. Pas dit toe per package, niet per map, en een repo met twaalf packages kan eindigen met twee echte changelogs en tien packages die er simpelweg geen nodig hebben.

Hoe weet je welk package welke changelog-regel veroorzaakte?

Label elke regel met zijn package op het moment dat de regel geschreven wordt, niet achteraf door te inspecteren welke bestanden een commit raakte. Een commit die een gedeelde interne bibliotheek fixt kan een changelog-regel opleveren in elk package dat ervan afhangt, en bestandspaden alleen kunnen niet zeggen welke van die stroomafwaartse regels de lezer echt moet zien; alleen een persoon die beslist "dit is zichtbaar voor gebruikers van package A en niet voor gebruikers van package B" kan dat. Conventional commits helpen hier mechanisch, door het package in elke commit te noemen, maar de scope levert nog steeds alleen een concept op. Dezelfde tweelaagse regel uit dat artikel geldt per package: een concept met de juiste scope heeft alsnog een menselijke pas nodig voordat het is verwoord voor de echte lezer van dat package.

Wat heeft een gedeelde changelog nodig dat een changelog voor één repo niet heeft?

Een package-label op elke regel, vooraan, voor de beschrijving, zodat een lezer die het log doorneemt in één keer alles kan overslaan dat niet van hem is. Zonder dat label leest een gedeeld log als een willekeurige feed, en een lezer die zich voor één package interesseert heeft geen manier om te filteren behalve onthouden welke regels tellen, wat niemand na de eerste week meer doet.

## 2026-09-07

### [cli] Toegevoegd
- `acme push --dry-run` laat zien wat verzonden zou worden
  zonder het echt te verzenden.

### [core] Opgelost
- De retry-backoff reset niet meer bij een succesvol verzoek dat
  een leeg body teruggeeft.

Twee regels, twee publieken, één blik om ze te onderscheiden. Een workflow in Changesets-stijl bouwt deze labeling rechtstreeks in het releaseproces: een bijdrager schrijft een korte, package-specifieke notitie naast zijn wijziging, en de tool stelt de changelogs per package en de versiesprongen samen uit die notities op het moment van de release, in plaats van te proberen packagegrenzen achteraf te reconstrueren uit een samengevoegde commitgeschiedenis.

Hoe verhoudt versionering zich tot een monorepo-changelog?

Onafhankelijk geversioneerde packages hebben hun eigen changelog nodig omdat ze hun eigen versienummer hebben, en een gedeelde changelog kan niet uitdrukken "package A ging van 2.1 naar 2.2 terwijl package B op 1.4 bleef" zonder twee logs in één bestand te worden. Semantic versioning en je changelog behandelt hoe een versienummer zou moeten mappen op changelog-categorieën; in een monorepo moet die mapping per package worden toegepast, omdat een breaking change in het ene package geen breaking change is voor een zusterpackage dat er niet van afhangt.

Een repo die één product uitbrengt als één uit te brengen eenheid, ook al is die opgebouwd uit veel interne packages, heeft dit probleem niet: de packages delen een versie omdat ze altijd samen worden uitgebracht, en één changelog is correct.

Hoe passen git-tags in een monorepo?

Dezelfde regel uit git-tags, releases en je changelog geldt, per package toegepast: een package met een eigen versie heeft een eigen tag-prefix nodig, typisch packagenaam@1.4.0 in plaats van een kale v1.4.0 die niet kan zeggen bij welk package het hoort. Een monorepo die alleen met kale versienummers is getagd, kan later niet beantwoorden "wat zat er in core toen cli 2.2 uitbracht", omdat niets op schijf vastlegt bij welk package die tag daadwerkelijk hoorde.

FAQ

Heb ik een aparte changelog nodig voor elk package in een monorepo? Alleen voor packages met een onafhankelijk publiek, meestal alles wat in een register wordt gepubliceerd. Een package met één interne afnemer die al in dezelfde repo leeft, kan opgaan in het log van die afnemer in plaats van een eigen log bij te houden.

Wat labelt een changelog-regel met het juiste package? De persoon die de regel schrijft, op het moment dat hij die schrijft, niet een automatische scan van gewijzigde bestandspaden. Een wijziging in een gedeelde bibliotheek kan een andere regel opleveren in elk package dat ervan afhangt, en alleen een mens kan beslissen wat elk van die stroomafwaartse regels eigenlijk moet zeggen.

Zou een monorepo één versienummer voor alles moeten gebruiken? Alleen als elk package altijd samen met de rest wordt uitgebracht. Als packages ooit onafhankelijk worden gepubliceerd, hebben ze onafhankelijke versies nodig, en onafhankelijke versies hebben onafhankelijke changelogs nodig om ergens op te slaan.

Vervangt een monorepo-changelogtool de menselijke redactiestap? Nee. Tools zoals Changesets automatiseren het verzamelen en samenstellen van notities per package op het moment van de release; de notitie zelf, geschreven in de taal van de lezer in plaats van die van de bijdrager, blijft net als bij elke andere changelog-pipeline het werk van een persoon.

Hoe je een nieuwe feature aankondigt (zonder stilte)

Mon, 07 Sep 2026 00:00:00 GMT

De meeste featureaankondigingen sterven in een kanaal dat niemand twee keer leest: een tweet die voorbijscrolt, een e-mail op releasedag begraven onder de andere twaalf die een abonnee die week kreeg, een Slack-bericht in een kanaal dat het halve team maanden geleden dempte. De feature kwam uit. Bijna niemand die het zou gebruiken, kwam erachter. Dat oplossen heeft minder te maken met een betere aankondiging schrijven en meer met het juiste kanaal kiezen voor de juiste lezer, en mensen die er expliciet om vroegen rechtstreeks bereiken in plaats van erop te vertrouwen dat ze een algemeen bericht opmerken.

Waar hoort een nieuwe feature eigenlijk aangekondigd te worden?

Op meer dan één plek, want "iedereen leest hetzelfde kanaal" is nooit waar. Een changelog- of feedregel bedient de lezer die op eigen tempo checkt en het permanente, gedateerde overzicht wil. Een melding in de app bedient de lezer die het product al gebruikt en de feature vandaag zou gebruiken als ze wisten dat die bestond. E-mail bedient de lezer die momenteel niet in het product zit maar zou terugkomen voor de juiste update. Social media bedient bereik voorbij bestaande gebruikers, met bijna geen targeting.

Kanaal	Beste voor	Zwakte
Changelog / feed	Het permanente overzicht; lezers op eigen tempo	Passief; doet niets voor wie nooit checkt
Melding in app	Gebruikers die al aanwezig zijn en vandaag zouden handelen	Bereikt niemand die nu niet ingelogd is
E-mail	Niet-actieve gebruikers die hiervoor zouden terugkeren	Snel begraven onder andere mail; heeft een echte onderwerpregel nodig
Social media	Bereik voorbij bestaande gebruikers	Bijna geen targeting; korte houdbaarheid

Geen van de vier is alleen voldoende. De changelog is het ene document dat elke release hoort te dragen ongeacht de grootte, omdat het het overzicht is waar al het andere naar terugverwijst; de andere drie zijn versterking daarbovenop, gekozen naar hoe groot de feature echt is.

Wat moet de aankondiging eerst zeggen?

Het resultaat, niet het mechanisme. "We voegden een cachelaag toe aan het rapporten-endpoint" beschrijft wat het team bouwde. "Rapporten laden nu in minder dan een seconde" beschrijft wat veranderde voor de lezer, en dat is de zin die de klik oplevert, omdat die "wat heb ik eraan" beantwoordt in de eerste bijzin in plaats van de derde. Het mechanisme hoort in de changelog-regel of de detailpagina, niet in de kop.

Concreet vóór bijvoeglijke naamwoorden. "Een snellere, krachtigere rapportenervaring" vertelt de lezer niets waar ze op kunnen handelen; "rapporten laden nu in minder dan een seconde en kunnen gefilterd worden op status" vertelt precies wat er veranderde en wat te proberen. De tweede versie komt ook geloofwaardiger over, omdat een vage bewering precies klinkt zoals marketingtekst klinkt als er niets concreets te zeggen valt.

Hoe verschilt dit van een productupdate-e-mail?

Overlappend maar niet identiek. Productupdate-e-mail behandelt het e-mailkanaal specifiek, inclusief cadans, onderwerpregels, en wanneer een digest een losse verzending verslaat. Een nieuwe-featureaankondiging is de onderliggende gebeurtenis; e-mail is een van de vier kanalen hierboven die het zou kunnen dragen, gekozen wanneer de feature groot genoeg is om een eigen verzending te rechtvaardigen in plaats van mee te liften in de volgende digest. Een kleine feature verdient een changelog-regel en misschien een melding in de app. Een significante verdient alle vier de kanalen, in de tijd op elkaar afgestemd.

Hoe bereik je precies de mensen die erom vroegen?

Dit is de aankondiging met het beste rendement, en bijna elk team slaat hem over. Als tien klanten een feature met naam aanvroegen, verdienen die tien mensen een directe, persoonlijke boodschap op het moment dat hij uitkomt, los van welke bredere aankondiging er ook uitgaat. De feedbackloop met de klant sluiten behandelt de mechaniek volledig; de samenvatting hier is dat dit alleen werkt als het oorspronkelijke verzoek gekoppeld bleef aan de aanvrager, wat meer een bijhoudprobleem is dan een aankondigingsprobleem. Bij changeloop geldt: wanneer widgetfeedback een GitHub-issue werd en de gemergede pull request dat issue sluit (fixes #142), plaatst het goedkeuren van de changelog-regel eenmalig een "Shipped — "-reactie op dat issue, met een link naar de live regel, en de persoon die de feedback stuurde ziet de uitgebrachte regel in de widget. Niemand hoeft te onthouden het te vertellen. Met de hand aangemaakte issues, en GitLab- of Bitbucket-repositories, krijgen de reactie niet.</p> <h2>Hoe schrijf je de regel zelf?</h2> <p>Dezelfde discipline als elke andere release notes-regel: begin met wat de lezer nu kan doen, gevolgd door benodigde setup, sla de interne rechtvaardiging over. <a href="https://changeloop.dev/blog/nl/how-to-write-release-notes/">Hoe schrijf je release notes</a> behandelt de volledige methode; een nieuwe-featureaankondiging is het geval met de hoogste inzet, omdat het de regel is die het meest waarschijnlijk gescreenshot, doorgestuurd, en gelezen wordt door iemand die nog nooit de changelog van het product zag.</p> <h2>Wanneer kondig je iets niet breed aan?</h2> <p>Wanneer de feature nog wordt uitgerold naar een subset accounts, echt een beta is, of zo geprijsd of afgeschermd is dat negen van de tien lezers van een brede aankondiging het nog niet zouden kunnen gebruiken. Een brede aankondiging voor een feature die negen van de tien lezers niet kunnen gebruiken, leest als lokaas, en verbrandt vertrouwen in de volgende aankondiging meer dan het enthousiasme opbouwt in deze. De oplossing is geen stilte, het is bereik: informeer de in aanmerking komende accounts rechtstreeks, en houd de brede kanalen achter tot beschikbaarheid de aankondiging inhaalt.</p> <h2>FAQ</h2> <p><strong>Verdient elke nieuwe feature een eigen aankondiging?</strong> Elke verdient een changelog-regel. Alleen degene die significant genoeg zijn om te veranderen hoe iemand het product gebruikt, of expliciet met naam werden aangevraagd, verdienen de bredere kanalen zoals e-mail of social media.</p> <p><strong>Wat is het beste kanaal voor een kleine feature?</strong> Alleen de changelog, plus een melding in de app als de feature vindbaar is in een flow waar de gebruiker al in zit. E-mail en social media zijn de moeite waard voor features die aandacht vragen rechtvaardigen.</p> <p><strong>Hoe kondig je een feature aan bij de mensen die er specifiek om vroegen?</strong> Houd het verzoek gekoppeld aan de aanvrager vanaf het moment van registratie, en informeer individueel bij uitkomen, apart van elke bredere aankondiging. Een gedeeld statuslabel dat de aanvrager zelf kan checken, vermindert ook hoeveel individuele berichten er sowieso nodig zijn.</p> <p><strong>Heeft een featureaankondiging een screenshot nodig?</strong> Voor alles visueels, ja; een beschreven maar ongeziene feature wordt veel vaker overgeslagen dan een waar lezers een preview van kunnen zien. Voor een API of backend-capaciteit doet een kort codevoorbeeld hetzelfde werk als een screenshot bij een UI-verandering.</p> </article> <article> <h1>Enterprise release notes: wat verandert voor één account</h1> <p>Mon, 07 Sep 2026 00:00:00 GMT</p> <p>Een publiek SaaS-product stuurt iedereen dezelfde release notes, omdat iedereen op dezelfde versie zit. Een enterprise-klant op een vastgezette versie, een dedicated instantie, of een subset van het product met feature flags doorbreekt die aanname: de release notes die beschrijven wat er voor haar is veranderd, zijn niet dezelfde als die op jullie publieke blog, en de publieke toch sturen verwart de klant ofwel met veranderingen die ze nog niet heeft, of, erger, vertelt haar over een functie die het accountteam van een andere enterprise-klant jullie expliciet heeft gevraagd nog een maand bij hen achter te houden. <a href="https://changeloop.dev/blog/nl/release-notes-best-practices/">Beste practices voor release notes</a> behandelt het algemene vakmanschap; dit gaat over het schrijven van enterprise release notes voor het afstemmingsprobleem dat opduikt zodra je klanten hebt die niet allemaal op dezelfde build zitten.</p> <h2>Waarom kan een enterprise-klant niet gewoon de publieke changelog lezen?</h2> <p>Omdat die een versie beschrijft die ze misschien nog niet draait, functies waar ze misschien geen toegang toe heeft, en een tijdlijn die niet overeenkomt met de hare. Een klant die vastzit aan een kwartaal-releasecyclus en leest over een functie die vorige week naar de publieke laag ging, heeft geen manier om, alleen uit de publieke changelog, te weten of die functie haar volgende week of volgend kwartaal bereikt. De publieke changelog beantwoordt "wat is er in het product veranderd"; de werkelijke vraag van een enterprise-klant is "wat is er veranderd in de versie die ik draai, en wanneer krijg ik de rest", iets waar de publieke changelog nooit voor is geschreven om te beantwoorden.</p> <h2>Wat heeft een private release note nodig dat een publieke niet nodig heeft?</h2> <p>Een versie- of omgevingsidentificatie waar de klant daadwerkelijk tegen kan controleren, en een expliciete verklaring van wat haar nog niet heeft bereikt. "Deze release bevat de bulk-exportverbeteringen uit onze publieke 4.3-release, maar niet het nieuwe permissiemodel, dat in jullie volgende geplande update verschijnt" vertelt een enterprise-beheerder precies waar haar instantie staat ten opzichte van het product in het algemeen. Een publieke release note heeft dit kader nooit nodig omdat er maar één instantie is om relatief aan te zijn; een private is betekenisloos zonder.</p> <table> <thead> <tr> <th>Publieke release notes</th> <th>Private (enterprise) release notes</th> </tr> </thead> <tbody><tr> <td>Eén versie, één publiek</td> <td>Meerdere versies, gesegmenteerde publieken</td> </tr> <tr> <td>Neemt aan dat de lezer elke beschreven functie heeft</td> <td>Moet vermelden wat de lezer wel en niet heeft</td> </tr> <tr> <td>Getimed op de publieke release</td> <td>Getimed op het eigen update-venster van de klant</td> </tr> <tr> <td>Kan meteen volledig publiek gemaakt worden</td> <td>Moet mogelijk items achterhouden die andere klanten nog niet hebben</td> </tr> </tbody></table> <h2>Is het ooit oké om het versturen van publieke release notes naar enterprise-klanten gewoon uit te stellen in plaats van aparte te schrijven?</h2> <p>Alleen als haar versie op dat moment echt overeenkomt met de publieke, wat zeldzamer is dan het klinkt zodra je meer dan een paar enterprise-accounts op verschillende ritmes hebt. De publieke notes uitstellen werkt als tijdelijke oplossing voor een klant die één versie achterloopt en op het punt staat in te halen; het breekt op het moment dat twee enterprise-klanten op verschillende versies van elkaar zitten, omdat er dan geen enkele "de notes" meer is om uit te stellen, alleen een matrix van wat elk heeft. Op dat punt houdt het afstemmen van notes per account, zelfs als het maar een gefilterde weergave is van dezelfde onderliggende entries, op om optioneel te zijn.</p> <pre><code>Publieke notes, gestuurd naar een enterprise-account dat de functie nog niet heeft: "New: Bulk export now supports custom column ordering." (Verwarrend: de admin probeert het en het is er niet.) Afgestemde enterprise-notes voor hetzelfde account: "Available in your next update (scheduled for 2026-10-15): bulk export with custom column ordering. Not yet available on your current version (3.8)." </code></pre> <h2>Wie binnen de organisatie van de klant leest dit eigenlijk, en verandert dat het schrijven?</h2> <p>Meestal een IT-beheerder of een customer-successcontact in plaats van een eindgebruiker, en dat verandert wat als nuttig telt. Een eindgebruiker wil weten wat er anders uitziet op haar scherm; een enterprise-beheerder wil weten wat er is veranderd in permissies, gegevensverwerking, SSO-configuratie, of iets dat beïnvloedt hoe ze de implementatie beheert voor haar eigen gebruikers, omdat zij degene zal zijn die de interne vragen beantwoordt. Een private release note die leest als een consumenten-changelog, allemaal glimmende nieuwe knoppen en geen operationeel detail, dwingt de beheerder om te graven naar de informatie die ze eigenlijk nodig had.</p> <h2>Hoe verhoudt dit zich tot een publieke roadmap of publieke changelog die dezelfde functie al vermeldt?</h2> <p>Voorzichtig, want een klant die beide leest zal elke inconsistentie opmerken. Als jullie publieke changelog al een functie heeft aangekondigd die een specifiek enterprise-account nog niet heeft, moet haar private release note dat gat erkennen in plaats van doen alsof de publieke entry niet bestaat; een beheerder die de publieke aankondiging heeft gezien en private notes krijgt die het negeren, zal ofwel aannemen dat jullie haar zijn vergeten, ofwel dat er iets kapot is. <a href="https://changeloop.dev/blog/nl/public-roadmap/">Publieke roadmap</a> behandelt hoe je een roadmap eerlijk houdt over wat is uitgebracht versus gepland; de enterprise-versie van die eerlijkheid in release notes is het gat tussen wat publiek is en wat van haar is direct benoemen.</p> <h2>Heeft een klein bedrijf met maar één of twee enterprise-klanten al die structuur nodig?</h2> <p>Niet het volledig gesegmenteerde systeem, maar de kerndiscipline, duidelijk vermelden op welke versie de klant zit en wat ze wel en niet heeft, telt op elke schaal zodra je zelfs maar één klant hebt die niet op jullie nieuwste build zit. Het faalmodus dat dit voorkomt, een beheerder die verward is of een publieke aankondiging op haar van toepassing is, kost een supportticket en een deuk in het vertrouwen ongeacht of jullie twee enterprise-accounts hebben of tweehonderd.</p> <h2>FAQ</h2> <p><strong>Zouden private release notes ooit functies moeten noemen die andere klanten al hebben maar deze niet?</strong> Alleen als het relevant is voor haar eigen tijdlijn, geformuleerd als "komt in jullie volgende update" in plaats van als vergelijking met andere klanten. Benoemen wat een specifieke andere klant heeft, overschrijdt terrein dat niet aan jullie is om te onthullen; benoemen wat specifiek naar deze klant komt is precies de informatie die ze nodig heeft.</p> <p><strong>Kunnen dezelfde onderliggende changelog-entries zowel publieke als private release notes voeden?</strong> Ja, en dat is meestal de beter onderhoudbare aanpak: label entries met welke versies of niveaus ze van toepassing zijn, en filter dan per publiek bij publicatie in plaats van twee volledig gescheiden documenten te schrijven die onvermijdelijk uit elkaar drijven.</p> <p><strong>Wat als een enterprise-klant expliciet vraagt om op de publieke release notes te staan in plaats van op een private feed?</strong> Respecteer het, maar bevestig dat ze begrijpt dat de publieke notes de publieke versie veronderstellen, en signaleer zelf schriftelijk het gat als haar versie afwijkt van wat is beschreven. Die schriftelijke bevestiging is wat jullie later beschermt als ze handelt naar publieke notes die eigenlijk niet van toepassing waren op haar build.</p> <p><strong>Hoe ver van tevoren zou een enterprise-klant op de hoogte moeten worden gebracht van een functie waar ze in de volgende release toegang toe krijgt?</strong> Zodra de datum is bevestigd, niet pas op het moment van de release, omdat enterprise-beheerders vaak hun eigen interne communicatie of training moeten plannen rond een functie die eraan komt, en een melding op dezelfde dag hen daar geen ruimte voor laat.</p> </article> <article> <h1>Featureverzoeken prioriteren die zich opstapelen</h1> <p>Mon, 07 Sep 2026 00:00:00 GMT</p> <p>Featureverzoeken bijhouden lost op waar ze leven. Het lost niet op welk verzoek eerst gaat, en die tweede vraag is waar teams echt op vastlopen. Een backlog van driehonderd gegroepeerde, gelabelde verzoeken heeft nog steeds een beslisregel nodig, omdat "bouw het meest gevraagde ding" alleen werkt totdat twee verzoeken dicht bij elkaar liggen en een derde een luidruchtige voorstander heeft, wat de meeste weken het geval is. De frameworks hieronder zijn geen concurrerende antwoorden op dezelfde vraag. Elk past bij een ander type verzoek, en er één voor alle gebruiken is meestal de eigenlijke fout.</p> <h2>Wat maakt featureverzoeken prioriteren anders dan een roadmap prioriteren?</h2> <p>Een roadmapbeslissing start bij de strategie en vraagt wat te bouwen. Een beslissing over een featureverzoek start bij vraag die al bestaat en vraagt of er actie op moet komen, en die twee trekken vaak genoeg in verschillende richtingen dat een verzoek veel vraag kan hebben en toch verkeerd is om te bouwen, of weinig vraag kan hebben en toch de moeite waard is omdat het een strategisch account ontgrendelt. Elk verzoek behandelen als een roadmapstem slaat die controle over.</p> <table> <thead> <tr> <th>Framework</th> <th>Wat het weegt</th> <th>Waar het breekt</th> </tr> </thead> <tbody><tr> <td>Ruwe verzoekentelling</td> <td>Hoeveel mensen vroegen</td> <td>Beloont pakkende namen boven echte vraag</td> </tr> <tr> <td>RICE</td> <td>Bereik, impact, vertrouwen, moeite</td> <td>Vereist schattingen die niemand heeft voor een vers verzoek</td> </tr> <tr> <td>Omzetgewogen</td> <td>Wie vroeg, naar accountwaarde</td> <td>Negeert verzoeken van accounts die nog niet veel waard zijn</td> </tr> <tr> <td>Publieke stemmen</td> <td>Zichtbaar, laagdrempelig signaal</td> <td>Bereikt alleen gebruikers die al weten waar te kijken</td> </tr> </tbody></table> <h2>Wat is RICE, en werkt het voor featureverzoeken?</h2> <p><a href="https://www.intercom.com/blog/rice-simple-prioritization-for-product-managers/">RICE</a> scoort een idee op bereik, impact, vertrouwen en moeite, en deelt dan de eerste drie door de vierde voor een vergelijkbaar getal. Het is gebouwd voor roadmap-ideeën waar een team al in gelooft, waar het lastige deel is om ongelijke weddenschappen met elkaar te vergelijken. Featureverzoeken komen al met een bereikcijfer, de telling van mensen die vroegen, wat concreter is dan het bereik dat een vers roadmap-idee gewoonlijk heeft. Waar RICE onder spanning komt bij een verzoek is vertrouwen en impact: een team kan er zeker van zijn dat een verzoek echt is en toch geen basis hebben voor hoe sterk het een metriek zal bewegen, omdat "impact" voor een verzoek dat al een naam en een spoor van echte gebruikers heeft een ander soort schatting is dan impact voor een idee dat nog niemand buiten de kamer heeft gezien.</p> <p>Gebruik RICE voor verzoeken die serieus worden overwogen en nog niet beslist zijn. Pas het niet toe op elk binnenkomend verzoek; de moeite van het scoren betaalt zich alleen uit bij verzoeken die dicht genoeg bij elkaar liggen om een tiebreaker nodig te hebben.</p> <h2>Moet je wegen naar omzet, of naar wie vroeg?</h2> <p>Naar wie vroeg, maar niet alleen naar omzet. Een account vlak voor verlenging, een account dat al eerder escaleerde, en een account waarvan het verzoek een lopende deal ontgrendelt, dragen een urgentie die een plat omzetcijfer alleen niet vastlegt, en een verzoek van een trialaccount kan nog steeds ertoe doen als het een beslissing blokkeert die binnenkort omzet wordt. Omzetweging is van deze het makkelijkst te berekenen, en juist daarom het makkelijkst om te veel op te vertrouwen: het haalt terecht ruis weg van accounts zonder echt belang, en het kan even makkelijk een verzoek degraderen dat een veel groter account zou binnenhalen dat nog in de pipeline zit.</p> <h2>Welke rol spelen stemmen eigenlijk?</h2> <p>Een goedkoop, doorlopend signaal voor verzoeken die al bestaan, en een slechte manier om te ontdekken welke verzoeken er überhaupt zouden moeten bestaan. Een stemmentelling bereikt alleen de gebruikers die het verzoek al vonden en het een klik waard vonden, wat betekent dat het totaal aan stemmen op een publieke roadmap net zoveel zichtbaarheid als vraag weerspiegelt: een oud verzoek hoog op de lijst blijft stemmen verzamelen deels omdat het makkelijk te vinden is, en een nieuwer, even echt verzoek begint bij nul. Het artikel over de <a href="https://changeloop.dev/blog/nl/public-roadmap/">publieke roadmap</a> pleit ervoor stemmen helemaal van de roadmap te houden. Behandel stemmen als een signaal dat gegroepeerd en gewogen naar recentheid moet worden, niet als een ranglijst die je in volgorde afwerkt. <a href="https://changeloop.dev/blog/nl/feedback-signal-quality/">Supporttickets vs. featureverzoeken</a> behandelt de andere blinde vlek in stemmenaantallen: een echt gat kan bijna geen stemmen opleveren als de gebruikers die het raken het bord nooit vinden, terwijl het luidruchtig verschijnt in support.</p> <h2>Wanneer wint de luidruchtigste klant, en is dat een probleem?</h2> <p>Soms, en het is alleen een probleem als niemand het opmerkt. Een klant die vaak escaleert, gedetailleerde tickets schrijft of een directe lijn heeft met iemand in het team, ziet zijn verzoeken sneller behandeld dan een stillere klant met een even geldig verzoek, en een prioriteringsproces dat dit nooit controleert zal systematisch degene bevoordelen die het meest aandringt, niet degene met de sterkste zaak. Luidruchtige klanten zijn niet het probleem dat opgelost moet worden; hun verzoeken zijn vaak echt belangrijk. De oplossing is een gewoonte: periodiek de backlog per bron doorlopen en controleren of dezelfde handvol accounts het meeste verklaart van wat recent is uitgebracht, en je afvragen of dat overeenkomt met waar de echte vraag zit.</p> <h2>Hoe wordt een prioriteringsbeslissing een reactie?</h2> <p>Elke beslissing hier produceert winnaars en verliezers, en beide verdienen een reactie die de werkelijke redenering noemt, niet alleen een statuswijziging zonder uitleg. <a href="https://changeloop.dev/blog/nl/declining-feature-requests/">Hoe je een featureverzoek afwijst</a> behandelt wat je zegt tegen een verzoek dat verloor, op een manier die de relatie intact houdt in plaats van als een generieke afwijzing te klinken. Het groeperings- en labelwerk dat dit alles mogelijk maakt wordt behandeld in <a href="https://changeloop.dev/blog/nl/feature-request-tracking/">featureverzoeken bijhouden</a>; prioriteren werkt alleen op verzoeken die al zijn geregistreerd en goed genoeg gegroepeerd om te vergelijken.</p> <h2>FAQ</h2> <p><strong>Wat is het beste framework om featureverzoeken te prioriteren?</strong> Geen enkele alleen. Gebruik ruwe tellingen om het luidruchtigste signaal te vinden, RICE om een korte lijst serieuze kandidaten te vergelijken, en een omzet- of accountcheck om gevallen te vangen waarin stille vraag van een strategisch account zwaarder weegt dan een luidruchtigere maar minder belangrijke groep.</p> <p><strong>Moeten featureverzoeken op dezelfde manier geprioriteerd worden als roadmap-ideeën?</strong> Nee. Roadmap-ideeën starten bij strategie; featureverzoeken starten bij vraag die al bestaat. Ze samen scoren zorgt ervoor dat een goed onderbouwde strategische weddenschap met weinig bestaande vraag consequent verliest van een verzoek dat gewoon meer mensen heeft die het vroegen.</p> <p><strong>Weerspiegelen stemmen op een publieke roadmap de vraag accuraat?</strong> Alleen onder mensen die het verzoek al vonden. Oudere, zichtbaardere verzoeken verzamelen sneller stemmen, ongeacht hoeveel echte vraag er achter een nieuwer verzoek zit, dus behandel stemtotalen als een signaal, gegroepeerd en gewogen naar recentheid, niet als een ranglijst die je in volgorde afwerkt.</p> <p><strong>Hoe vaak moeten prioriteiten van featureverzoeken opnieuw beoordeeld worden?</strong> Op een vaste cyclus, niet alleen wanneer iemand escaleert. Een maandelijkse of driemaandelijkse ronde die verzoeken hergroepeert en de weging herbekijkt, vangt afwijking op, zoals een handvol accounts dat domineert wat er wordt uitgebracht, wat een puur reactief proces nooit zelf naar boven brengt.</p> </article> <article> <h1>Semantic versioning en je changelog</h1> <p>Mon, 07 Sep 2026 00:00:00 GMT</p> <p>Semantic versioning vertelt een aanroeper hoeveel pijn een release kan doen voordat ze één changelog-regel hebben gelezen. Van <code>2.4.1</code> naar <code>2.5.0</code> zegt: nieuwe capaciteit, niets breekt. Van <code>2.5.0</code> naar <code>3.0.0</code> zegt: lees deze regel voor je update. Changelog en versienummer horen hetzelfde te beweren in twee formaten, en de meeste wrijving tussen de twee duikt precies op wanneer ze het oneens zijn, wat vaker gebeurt dan de specificatie zou suggereren.</p> <h2>Wat belooft elk cijfer in een versie eigenlijk?</h2> <p><a href="https://semver.org/">Semantic versioning</a> definieert drie cijfers, <code>MAJOR.MINOR.PATCH</code>, elk met een strikte regel over wat het triggert. Een MAJOR-sprong betekent een breaking change: iets wat een correcte, bestaande integratie zou kunnen opmerken en waarvoor ze zouden moeten veranderen. Een MINOR-sprong betekent nieuwe, achterwaarts compatibele functionaliteit: niets bestaands breekt, iets nieuws is beschikbaar. Een PATCH-sprong betekent een achterwaarts compatibele fix: gedrag komt dichter bij wat gedocumenteerd was, en niemand die opzettelijk vertrouwde op het oude gedrag zou iets moeten merken.</p> <table> <thead> <tr> <th>Sprong</th> <th>Betekenis</th> <th>Regel hoort te lezen als</th> </tr> </thead> <tbody><tr> <td>MAJOR (<code>1.x.x</code> -> <code>2.0.0</code>)</td> <td>Een breaking change</td> <td>"Actie nodig voor je update"</td> </tr> <tr> <td>MINOR (<code>1.2.x</code> -> <code>1.3.0</code>)</td> <td>Nieuwe, compatibele capaciteit</td> <td>"Nu beschikbaar, verder niets veranderd"</td> </tr> <tr> <td>PATCH (<code>1.2.3</code> -> <code>1.2.4</code>)</td> <td>Een compatibele fix</td> <td>"Gedraagt zich nu zoals gedocumenteerd"</td> </tr> </tbody></table> <p>De tabel is ook een test die achterstevoren werkt: als een regel niet leest als zijn rij, klopt of het versienummer niet, of verkoopt de regel wat er echt gebeurde te klein of te groot.</p> <h2>Wat telt als breaking voor versioneringsdoeleinden?</h2> <p>Dezelfde test die bepaalt of iets thuishoort in een API-changelog: of een correcte aanroeper, geschreven tegen het oude gedrag en sindsdien onaangeraakt, zich anders zou kunnen gedragen door deze verandering. <a href="https://changeloop.dev/blog/nl/breaking-changes/">Wat is een breaking change, en hoe breng je die uit</a> behandelt de beslissing volledig, inclusief gevallen die breaking lijken en dat niet zijn, en die klein lijken en dat niet zijn. Kort voor versioneringsdoeleinden: als het antwoord ja is, is de sprong MAJOR ongeacht hoeveel code de verandering intern echt raakte. Versienummers volgen het gevolg voor de aanroeper, niet de inspanning van het team.</p> <h2>Hoe moet een changelog-regel overeenkomen met een versiesprong?</h2> <p>Eén regel, één sprongcategorie, meteen vooraan genoemd. Het patroon uit de tabel zet zich direct voort: een breaking regel staat onder de versie die het introduceerde, eerst geformuleerd als waarschuwing en dan als beschrijving. Een additieve regel staat onder zijn MINOR-versie, geformuleerd als beschikbaarheid. Een fix staat onder zijn PATCH-versie, geformuleerd als correctie. Categorieën mengen in één regel, zoals een breaking change in dezelfde alinea vouwen als een ongerelateerde fix, is hoe een lezer precies het ene mist dat er echt toe deed.</p> <pre><code>## 3.0.0 (2026-09-07) ### Changed - **BREAKING:** `GET /reports` geeft bedragen nu terug als gehele getallen in de kleinste valuta-eenheid (centen) in plaats van decimalen. Werk code bij die `amount` rechtstreeks leest. ## 2.9.0 (2026-09-01) ### Added - Rapporten kunnen nu gefilterd worden op `status`. ## 2.8.4 (2026-08-28) ### Fixed - `GET /reports?status=` gaf een lege pagina terug in plaats van een 400 voor een onbekende status. </code></pre> <p>Van boven naar beneden gelezen zeggen versienummer en sectielabel hetzelfde twee keer, en dat is precies het doel: een lezer die alleen de koppen scant, krijgt een correcte risico-inschatting voordat ze ook maar één regel openen.</p> <h2>Geldt de breaking-change-regel op dezelfde manier vóór 1.0.0?</h2> <p>Nee, en dat is waar het meeste van de verwarring over "was dat nu echt breaking" vandaan komt. SemVer is expliciet dat hoofdversie nul, <code>0.y.z</code>, bedoeld is voor initiële ontwikkeling: alles mag op elk moment veranderen, en de publieke API zou niet als stabiel moeten worden beschouwd. Een sprong van <code>0.4.0</code> naar <code>0.5.0</code> kan een breaking change bevatten zonder de spec te schenden, omdat de garantie op hoofdversie pas begint zodra een project <code>1.0.0</code> uitbrengt. Een changelog-regel is lezers nog steeds dezelfde eerlijkheid schuldig over wat er kapot ging; wat verandert is alleen dat het versienummer zelf niet het signaal is om op te vertrouwen voordat 1.0.0 arriveert.</p> <h2>Wat als je product geen discrete versies uitbrengt?</h2> <p>De meeste SaaS-producten deployen continu en tonen een aanroeper nooit een versienummer, wat de noodzaak van deze discipline niet wegneemt, alleen het cijfer dat het normaal zou dragen. De changelog-regel moet al het werk alleen doen: duidelijk zeggen of een verandering breaking, additief, of een fix is, met dezelfde drie woorden die semantic versioning gebruikt, ook zonder versieveld om ze aan te hangen. Sommige teams houden een puur interne versie bij, alleen om changelog-regels te verankeren aan iets linkbaars, zonder het ooit rechtstreeks aan de aanroeper te tonen.</p> <h2>Hoe geldt dit specifiek voor een API-changelog?</h2> <p>Strenger dan bijna overal elders, omdat aanroepers van een API code zijn, geen mensen die met de schouders kunnen ophalen bij een onverwachte verandering. <a href="https://changeloop.dev/blog/nl/api-changelog/">API-changelog: wat te publiceren en wie het leest</a> behandelt de volledige vorm van dat document; de versioneringsdiscipline hier houdt de breaking- en additieve secties eerlijk. Een API die meerdere versies tegelijk aanbiedt, zoals <code>v1</code> en <code>v2</code> parallel bediend tijdens een migratievenster, past semantic versioning in de praktijk toe op het niveau van de hele interface in plaats van één pakket, en hetzelfde drieledige vocabulaire geldt nog steeds voor elke regel.</p> <h2>Wat zegt Keep a Changelog over versionering?</h2> <p>Het koppelt zich rechtstreeks bij naam aan semantic versioning en beveelt hetzelfde categorievocabulaire aan dat dit artikel gebruikt: Added, Changed, Deprecated, Removed, Fixed, Security. <a href="https://changeloop.dev/blog/nl/keep-a-changelog-implemented/">Keep a Changelog, in de praktijk</a> loopt door hoe je die specificatie in de praktijk toepast, inclusief waar teams meestal afdwalen. De overlap is geen toeval: beide specificaties proberen hetzelfde probleem vanaf tegenovergestelde kanten op te lossen, de ene standaardiseert het versienummer en de andere de regel die het uitlegt.</p> <h2>FAQ</h2> <p><strong>Heeft elke changelog-regel een versienummer nodig?</strong> Als het product versies uitbrengt, ja, omdat het cijfer een lezer toelaat direct naar "hoeveel raakt dit mij" te springen zonder de regel eerst te lezen. Als het product continu deployt zonder versieveld, moet de formulering van de regel dat signaal alleen dragen.</p> <p><strong>Wat is het verschil tussen een MAJOR-sprong en een breaking-change-regel?</strong> Ze horen hetzelfde evenement op twee manieren te beschrijven. Het versienummer is het machine-leesbare signaal (tooling van de aanroeper kan erop reageren); de changelog-regel is de mensleesbare uitleg van wat er concreet veranderde.</p> <p><strong>Kan een PATCH-release breaking zijn?</strong> Per definitie zou dat niet moeten. Is er toch een uitgebracht, bewerk of hertag de gepubliceerde versie dan niet: de <a href="https://semver.org/#what-do-i-do-if-i-accidentally-release-a-backward-incompatible-change-as-a-minor-version">SemVer-FAQ</a> zegt een nieuwe versie uit te brengen die de compatibiliteit herstelt, of een nieuwe MAJOR als de breuk blijft, en de betreffende versie te documenteren zodat gebruikers weten dat ze die moeten overslaan.</p> <p><strong>Hebben puur interne veranderingen een versiesprong nodig?</strong> Nee. Semantic versioning volgt de publieke interface. Een refactor zonder waarneembaar effect voor een aanroeper heeft geen sprong of changelog-regel nodig, zelfs als het intern significant engineeringwerk was.</p> </article> <article> <h1>De API sunset header, en wanneer je er een moet sturen</h1> <p>Mon, 07 Sep 2026 00:00:00 GMT</p> <p><code>Sunset</code> is één enkele responseheader, gedefinieerd in <a href="https://www.rfc-editor.org/rfc/rfc8594">RFC 8594</a>, die een aanroeper vertelt wanneer een resource stopt met antwoorden. <a href="https://changeloop.dev/blog/nl/api-deprecation/">API-deprecatie</a> behandelt de volledige tijdlijn van aankondigen, herinneren, brownout en uitfaseren en de bijbehorende berichten; dit gaat over het ene machineleesbare signaal in die tijdlijn, wat het daadwerkelijk zegt, en het ene geval waarin de RFC zelf zegt dat je hem niet moet sturen.</p> <h2>Wat zegt de Sunset-header wel, en wat zegt hij niet?</h2> <p>Hij bevat één HTTP-datum: het moment waarop de resource naar verwachting niet meer reageert:</p> <pre><code>Sunset: Sat, 31 Dec 2028 23:59:59 GMT </code></pre> <p>De RFC noemt het een aanwijzing, geen garantie: hij belooft niet dat de resource tot dat tijdstip blijft werken, en hij zegt niets over hoe een storing er daarna uitziet. Aanroepers kunnen een 4xx, een redirect of helemaal geen respons krijgen; de header maakt geen onderscheid. Een tijdstip dat al in het verleden ligt, betekent "nu, of op elk moment" en niet een fout in de waarde. Niets hiervan wordt afgedwongen door het protocol. Een client die de header nooit leest, gedraagt zich precies zoals altijd, en ontdekt dat de resource weg is op dezelfde manier als hij dat toch al zou hebben gedaan.</p> <h2>Wanneer zou je hem daadwerkelijk moeten sturen?</h2> <p>Alleen zodra de resource daadwerkelijk gaat stoppen met antwoorden, niet zodra hij simpelweg niet meer de aanbevolen keuze is. De RFC is expliciet dat deprecatie in twee fasen verloopt, en het Sunset-headerveld hoort alleen bij de tweede: de API blijft volledig operationeel tijdens de eerste fase, de aankondiging dat een versie niet meer de voorkeur heeft, en het headerveld is daar niet van toepassing. Het is van toepassing zodra de versie daadwerkelijk gepland staat om niet meer te reageren.</p> <p>Dat komt direct overeen met de deprecatietijdlijn: de <code>Deprecation</code>-header gaat vanaf dag één de deur uit, bij de aankondigingsstap; <code>Sunset</code> beschrijft de datum waarop het oude gedrag daadwerkelijk stopt, dezelfde datum die <a href="https://changeloop.dev/blog/nl/api-deprecation/">de vierstappentijdlijn</a> de uitfasering noemt. <code>Sunset</code> op dag één versturen is niet fout, omdat de datum dan al vaststaat, maar hem sturen zonder ook een deprecatie te hebben aangekondigd, of hem instellen voor een versie waarvan jullie nog niet echt hebben besloten hem uit te faseren, vertelt aanroepers iets wat jullie zelf nog niet hebben beslist.</p> <h2>Heeft dit invloed op caching?</h2> <p>Nee, en de RFC zegt dat expliciet: <code>Sunset</code> en HTTP-caching lossen niet-verwante problemen op en moeten worden gelezen als aanvullend, niet overlappend. Cachingheaders zeggen wanneer een gecachte kopie veilig te hergebruiken is; <code>Sunset</code> zegt niets over de huidige status van de resource, alleen dat de resource zelf ophoudt te bestaan. Een respons kan volledig cachebaar zijn tot vlak voor het moment waarop hij op sunset gaat. Gebruik het ene niet om het andere te benaderen, en neem niet aan dat een lange <code>max-age</code> een naderende sunsetdatum tenietdoet, of andersom.</p> <h2>Kan één header meer dan één endpoint op sunset zetten?</h2> <p>De header is van toepassing op de resource die hem teruggaf, maar de RFC staat een dienst toe om een breder bereik te documenteren: een sunsetdatum op de homeresource van een API kan zo worden gedefinieerd dat de hele API verdwijnt, niet alleen die ene URL. De valkuil is dat dit alleen werkt voor aanroepers die jullie afbakeningsregel al kennen. Een aanroeper die de header op waarde leest, ziet een sunset op de ene resource die hij opvroeg en verder niets, dus een breder bereik moet ergens worden vastgelegd waar een aanroeper het kan vinden, niet worden verondersteld.</p> <h2>Wat hoort er naast de header mee te gaan?</h2> <p>Een link naar waar de uitfasering wordt uitgelegd. RFC 8594 registreert hiervoor een eigen <code>sunset</code>-linkrelatie: die wijst naar een resource die het uitfaseringsbeleid, de aankomende datum of hoe te migreren beschrijft, los van de kale tijdstempel van de header.</p> <pre><code>HTTP/1.1 200 OK Sunset: Sat, 31 Dec 2028 23:59:59 GMT Link: <https://example.com/docs/sunset-policy>; rel="sunset" </code></pre> <p>Die link naar jullie eigen <a href="https://changeloop.dev/changelog-examples">changelog-voorbeelden</a> of een aparte migratiepagina wijzen, maakt van een header die vrijwel geen enkele clientcode inspecteert iets wat een mens die wel gaat zoeken meteen vindt. Combineer het met de <code>successor-version</code>-relatie uit <a href="https://changeloop.dev/blog/nl/api-deprecation/#which-headers-should-a-deprecated-endpoint-send">de deprecatieheaders</a> en een aanroeper krijgt uit de respons alleen al zowel waar hij heen moet als wat dit vervangt.</p> <h2>Hoe ziet dit er van begin tot eind uit?</h2> <p>Stel dat <code>v1</code> verdwijnt op 1 maart 2027. De deprecatieaankondiging voegt op dag één <code>Deprecation</code> en <code>Link: rel="successor-version"</code> toe aan elke <code>v1</code>-respons, volgens <a href="https://changeloop.dev/blog/nl/api-deprecation/">de deprecatieheaders</a>, maar wacht met <code>Sunset</code> totdat de uitfaseringsdatum echt vaststaat en geen placeholder meer is. Zodra dat zo is, draagt elke <code>v1</code>-respons:</p> <pre><code>HTTP/1.1 200 OK Deprecation: @1756425600 Sunset: Mon, 01 Mar 2027 00:00:00 GMT Link: <https://api.example.com/v2/reports>; rel="successor-version" Link: <https://example.com/docs/sunset-policy>; rel="sunset" </code></pre> <p>De gateway of monitoring van een aanroeper kan onafhankelijk alarmeren op elke header: <code>Deprecation</code> zegt dat er een nieuwere versie bestaat, <code>Sunset</code> zegt dat deze een klok heeft lopen. Geen van beide headers hoeft te veranderen vóór 1 maart; wat verandert is de respons zelf, op de dag zelf, en tijdens eventuele brownoutvensters die daarvoor gepland staan.</p> <h2>Verandert een brownout wat de header zegt?</h2> <p>De headerwaarde zelf hoeft niet te veranderen voor een geplande brownout: de sunsetdatum blijft de sunsetdatum, of de resource daarvoor nu af en toe uitvalt of niet. Wat verandert is de respons, niet de header. Korte vensters van <code>410 Gone</code> plannen in de weken voor de aangekondigde datum, zoals <a href="https://changeloop.dev/blog/nl/api-deprecation/">API-deprecatie</a> beschrijft, is wat het eerste contact van een aanroeper met de storing verandert in een generale repetitie in plaats van het echte werk op de dag dat de datum van de header aanbreekt.</p> <h2>FAQ</h2> <p><strong>Lezen echte HTTP-clients of tools de Sunset-header eigenlijk wel?</strong> Zelden, aan de clientzijde. De waarde ervan is vooral voor wie de infrastructuur tussen jullie en de aanroeper beheert: een API-gateway of een monitoringtool die je configureert om op de header te letten, kan jullie eigen team, of dat van een partner, ruim op tijd waarschuwen voordat de code van de aanroeper er ooit iets van zou merken. Behandel het als een signaal waar je zelf tooling omheen bouwt, niet een die je kunt aannemen dat de andere kant al heeft.</p> <p><strong>Is <code>Sunset</code> hetzelfde als <code>Cache-Control: max-age</code>?</strong> Nee. <code>max-age</code> gaat over hoe lang een gecachte kopie geldig blijft; <code>Sunset</code> gaat over wanneer de resource helemaal ophoudt te bestaan. Een respons kan een korte <code>max-age</code> dragen en een <code>Sunset</code>-datum die jaren verder ligt, of andersom, en geen van beide headers beperkt de andere.</p> <p><strong>Kan ik Sunset sturen voor één veld dat verdwijnt, niet het hele endpoint?</strong> Nee, de header is gebonden aan de resource, dus de URL, niet aan een veld binnen de responsebody. Gebruik voor een veld, een parameter of een enum-waarde die verdwijnt terwijl het endpoint zelf blijft bestaan, in plaats daarvan de <code>Deprecation</code>-header en een changelog-entry; <a href="https://changeloop.dev/blog/nl/api-deprecation/">API-deprecatie</a> behandelt precies het aankondigen van dat soort wijziging.</p> <p><strong>Wat als de sunsetdatum moet verschuiven?</strong> Werk de headerwaarde bij en meld dat in de changelog-entry die hem oorspronkelijk aankondigde; een gepubliceerde datum stilzwijgend veranderen is hoe een aanroeper besluit dat geen van jullie datums echt is. De RFC omschrijft de waarde als een aanwijzing juist omdat datums soms verschuiven, maar een verschoven datum zonder uitleg kost je ook de volgende.</p> </article> <article> <h1>Webhook-changelogs: de breaking change die niemand vroeg</h1> <p>Mon, 07 Sep 2026 00:00:00 GMT</p> <p>Een REST API-changelog bestaat omdat een aanroeper een respons die hij niet begrijpt kan afwijzen, of op zijn minst een fout luid genoeg logt dat iemand het merkt. Een webhook-ontvanger doet zelden een van beide. Hij krijgt een POST, leest de velden die hij verwacht, en als een veld is verplaatst, van type is veranderd of verdwenen is, crasht het endpoint stilletjes in een achtergrondtaak die niemand in de gaten houdt, of, erger, blijft het draaien met een verkeerde waarde die het nooit heeft gevalideerd. <a href="https://changeloop.dev/blog/nl/breaking-changes/">Wat is een breaking change</a> behandelt de algemene definitie; een webhook-payload heeft zijn eigen antwoord nodig, omdat het faalpatroon anders is dan bij een endpoint dat iemand doelbewust aanroept.</p> <h2>Waarom breekt een webhook-payloadwijziging anders dan een wijziging in een API-respons?</h2> <p>Omdat de richting van het verzoek omgekeerd is. Een REST-aanroeper initieert de aanroep en kan een versieheader toevoegen, opnieuw proberen bij een 4xx, of een deprecation-melding in de respons lezen. Een webhook-ontvanger heeft niets daarvan geïnitieerd: jullie server besloot te versturen, besloot wanneer, en besloot welke vorm de body zou hebben. De enige hendel van de ontvanger is de validatie die hij schreef toen de integratie werd gebouwd, en de meeste integraties worden één keer gebouwd, werken, en worden nooit meer herzien totdat ze breken. Die asymmetrie is de hele reden waarom een webhook-payloadwijziging meer voorzichtigheid verdient dan dezelfde wijziging in een responsbody die een aanroeper actief heeft aangevraagd.</p> <h2>Wat telt echt als breaking change in een webhook-payload?</h2> <table> <thead> <tr> <th>Wijziging</th> <th>Breaking voor de meeste ontvangers</th> </tr> </thead> <tbody><tr> <td>Een nieuw veld toevoegen</td> <td>Nee, als ontvangers onbekende velden negeren (verifieer deze aanname, neem hem niet aan)</td> </tr> <tr> <td>Een veld verwijderen</td> <td>Ja, als iets het leest</td> </tr> <tr> <td>Een veld hernoemen</td> <td>Ja, functioneel identiek aan het oude verwijderen</td> </tr> <tr> <td>Het type van een veld wijzigen (string naar object)</td> <td>Ja, bijna altijd</td> </tr> <tr> <td>Velden in de JSON-body herordenen</td> <td>Nee, voor elke ontvanger die op sleutel parset, wat ze allemaal zouden moeten zijn</td> </tr> <tr> <td>De event-naam of -type wijzigen</td> <td>Ja, als ontvangers erop filteren of routeren</td> </tr> </tbody></table> <p>De regel "een veld toevoegen is veilig" is degene waar teams het meest op leunen en degene die het meest waard is om te verifiëren in plaats van aan te nemen. Een permissieve JSON-parser negeert onbekende velden standaard, maar een ontvanger die deserialiseert naar een strikt schema, verschillende getypeerde talen doen dit zonder extra configuratie, kan de hele payload afwijzen zodra een onverwacht veld verschijnt. Een veld toevoegen is voor jullie webhook alleen veilig als je weet hoe ontvangers parsen, niet omdat JSON zelf permissief is.</p> <h2>Hoe versieer je een webhook-payload?</h2> <p>Grotendeels zoals bij een API-respons, met één nuance: de ontvanger stuurt nooit een verzoek, dus kan hij niet om een versie vragen, en moet de afzender die vermelden. Dat kan in de body of in een request-header op de levering zelf; <a href="https://docs.github.com/en/webhooks/webhook-events-and-payloads">de leveringen van GitHub</a> bevatten <code>X-GitHub-Event</code> en <code>X-GitHub-Hook-ID</code>, en de <a href="https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md">Standard Webhooks-specificatie</a> zet haar metadata in <code>webhook-*</code>-headers. Een versieveld in de payload (<code>"payload_version": 2</code>) is de goedkoopste optie en werkt wanneer ontvangers bereid zijn erop te vertakken. Een geversioneerd event-type (<code>invoice.updated</code> wordt <code>invoice.updated.v2</code> als een apart event waarop een ontvanger vrijwillig intekent) kost meer werk om te bouwen maar betekent dat de oude vorm blijft stromen naar wie nooit migreerde, wat hier meer telt dan bij een REST-endpoint omdat je niet elke ontvanger kunt bellen om te vragen te updaten. Een instelling per abonnement, gekozen bij registratie van het webhook-endpoint, neemt de beslissing vooraf in plaats van te vertakken bij elke levering, en is de juiste keuze wanneer je al een abonnementsrecord hebt om hem aan te hangen.</p> <pre><code>POST /ontvanger-endpoint { "event": "invoice.updated", "payload_version": 2, "data": { "invoice_id": "inv_123", "status": "paid" } } </code></pre> <h2>Hoe weet je überhaupt wie luistert?</h2> <p>Erger dan de equivalente versie van dit probleem in een API-changelog, omdat een webhook geen inkomend verzoeklog aan jullie kant heeft dat de aanroeper noemt; je hebt alleen jullie eigen uitgaande leveringslog, die vertelt dat een endpoint een 200 kreeg, niet wat het met de body deed. Volg minstens twee dingen: elk geregistreerd endpoint met een eigenaar, dezelfde discipline die <a href="https://changeloop.dev/blog/nl/internal-api-changelog/">interne API-changelogs</a> aanbevelen voor interne consumenten, en jullie leveringsfoutpercentage per endpoint na een payloadwijziging. Een piek in 4xx- of 5xx-responses van een endpoint vlak na een wijziging is het dichtst bij een stack trace dat je krijgt, en vaak het enige signaal dat een ontvanger kapot is, omdat het team dat hem beheert het dagenlang niet merkt.</p> <h2>Moet een webhook-changelog los staan van de API-changelog?</h2> <p>Een aparte sectie op dezelfde pagina, geen aparte publicatie. <a href="https://changeloop.dev/blog/nl/api-changelog/">Een API-changelog</a> legt al vast wie hem leest en hoe erop geabonneerd wordt; een webhook-payloadwijziging hoort in dezelfde feed, duidelijk genoeg gelabeld dat een ontwikkelaar aan ontvangerskant die scant op "raakt dit mijn integratie" erop kan filteren, omdat een webhook-consument vaak geen andere reden heeft om een algemene API-changelog te checken en hem alleen vindt als iemand haar er direct naartoe linkt.</p> <h2>Hoe ziet een redelijk deprecation-venster eruit voor een webhook-payload?</h2> <p>Langer dan de equivalente REST-deprecatie, omdat migratie aan ontvangerskant meestal betekent dat een tweede team, waarmee je misschien geen directe lijn hebt, het moet opmerken, plannen en uitleveren zonder eigen urgentie. Een maand is een redelijke ondergrens voor een veld dat de ontvanger waarschijnlijk nog parset met een permissieve library; drie maanden of meer is veiliger voor het verwijderen van een veld dat een strikt schema volledig zou afwijzen. Stuur de oude en nieuwe vorm samen tijdens het venster wanneer haalbaar (het oude <code>status</code>-veld en zijn vervanger uit versie 2 in dezelfde payload), omdat een ontvanger die het oude veld leest blijft werken zonder zijn code aan te raken, en een die al gemigreerd is het veld dat hij niet meer nodig heeft gewoon negeert.</p> <h2>FAQ</h2> <p><strong>Moeten webhook-consumenten een payloadwijziging bevestigen voordat hij live gaat?</strong> Er bestaat standaard geen bevestigingsmechanisme, en precies daarom telt het deprecation-venster hier meer dan bij een REST-API: niemand bevestigt klaar te zijn, dus het venster moet lang genoeg zijn dat de meeste ontvangers op hun eigen tempo migreren voordat de oude vorm verdwijnt.</p> <p><strong>Is het ooit veilig om onbekende velden zonder kennisgeving toe te voegen?</strong> Alleen zodra je hebt geverifieerd, niet aangenomen, dat jullie ontvangers permissief parsen. Een changelog-item kost weinig en haalt het giswerk weg; stilletjes velden toevoegen op de aanname dat "JSON-parsers extra's negeren" breekt elke ontvanger met strikte deserialisatie.</p> <p><strong>Wat is de snelste manier om een kapotte webhook-ontvanger te detecteren na een payloadwijziging?</strong> Een leveringsfoutpercentage per endpoint, geobserveerd in de uren vlak na de wijziging. Het vertelt je niet wat er kapot is, alleen dat er iets kapot is, maar het is het vroegste en vaak het enige signaal dat je krijgt.</p> <p><strong>Helpt retry-logica ontvangers om een payloadwijziging te overleven?</strong> Nee. Een retry stuurt dezelfde nieuwe payload opnieuw; hij keert niet terug naar een vorm die de ontvanger kan parsen. Een payloadwijziging breekt een ontvanger bij de eerste levering en elke volgende retry identiek.</p> </article> <article> <h1>Changelog: wat is het? Met een voorbeeld</h1> <p>Mon, 07 Sep 2026 00:00:00 GMT</p> <p>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.</p> <h2>Wat is een changelog, precies?</h2> <p>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.</p> <p>Het format is oud en bewust eenvoudig: een kop per release of per dag, een korte lijst eronder, soms een categorie-label. <a href="https://keepachangelog.com/en/1.1.0/">Keep a Changelog</a> 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.</p> <table> <thead> <tr> <th>Document</th> <th>Geschreven voor</th> <th>Beantwoordt</th> </tr> </thead> <tbody><tr> <td>Changelog</td> <td>Iedereen die het product gebruikt</td> <td>Wat veranderde er, en wanneer?</td> </tr> <tr> <td>Commit log</td> <td>Het team dat de code schreef</td> <td>Wat is er gedaan, in welke volgorde?</td> </tr> <tr> <td>Release notes</td> <td>Gebruikers die beslissen om te updaten</td> <td>Wat kan ik nu wat ik eerst niet kon?</td> </tr> <tr> <td>Patch notes</td> <td>Spelers of gebruikers van een specifieke fix</td> <td>Wat heeft precies deze release opgelost?</td> </tr> <tr> <td>Roadmap</td> <td>Iedereen die zich afvraagt wat er komt</td> <td>Wat is gepland, en hoever staat het?</td> </tr> </tbody></table> <p>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.</p> <h2>Wat bevat een changelog-regel eigenlijk?</h2> <p>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.</p> <pre><code>## 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. </code></pre> <p>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.</p> <h2>Wie schrijft een changelog, en wanneer?</h2> <p>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.</p> <h2>Waar hoort een changelog te staan?</h2> <p>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.</p> <h2>Hoe verschilt het van release notes?</h2> <p>De twee worden constant door elkaar gehaald, en verschillen genoeg dat ze samenvoegen een document oplevert dat geen van beide lezers goed dient. <a href="https://changeloop.dev/blog/nl/changelog-vs-release-notes/">Changelog vs release notes</a> 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.</p> <h2>Wat maakt een changelog het lezen waard?</h2> <p>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.</p> <p>Versioneringsdiscipline telt ook. <a href="https://changeloop.dev/blog/nl/semantic-versioning-changelog/">Semantic versioning en je changelog</a> 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.</p> <h2>Hoe worden changelogs gegenereerd?</h2> <p>Op twee manieren, en de meeste echte opzetten zijn een mix. Geautomatiseerde generatie leest commit-berichten, meestal in <a href="https://www.conventionalcommits.org/en/v1.0.0/">Conventional Commits</a>-formaat, en zet die om in regels zonder dat iemand de output aanraakt; <a href="https://changeloop.dev/blog/nl/conventional-commits-changelog/">van conventional commits naar changelog</a> 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.</p> <h2>FAQ</h2> <p><strong>Heeft elk product een changelog nodig?</strong> 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.</p> <p><strong>Wat is een changelog in softwaretermen?</strong> 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.</p> <p><strong>Kan een changelog automatisch gegenereerd worden uit commits?</strong> 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.</p> <p><strong>Is een changelog hetzelfde als een versiegeschiedenis?</strong> 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.</p> </article> <article> <h1>API-changelog: wat je publiceert, en wie het leest</h1> <p>Wed, 02 Sep 2026 00:00:00 GMT</p> <p>Een API-changelog is het gedateerde overzicht van elke wijziging die een aanroeper zou kunnen opmerken, geschreven voor wie tegen de API integreert, niet voor het team dat hem uitbrengt. Dat publiek maakt het een ander document dan een productchangelog: de lezer beslist of zijn code volgende maand nog werkt. De meeste falen op dezelfde manier, als gefilterde kopie van een interne release-feed, waardoor een verwijderd veld naast een tekstcorrectie staat met hetzelfde gewicht, en geen van beide wordt gelezen.</p> <h2>Wat is een API-changelog?</h2> <p>Het is het publieke, gedateerde logboek van wijzigingen aan een interface waar anderen code tegen hebben geschreven. De bruikbare test of iets erin thuishoort heeft niets te maken met hoe groot de wijziging intern was. Hij vraagt of een correcte aanroeper, vorig jaar geschreven en sindsdien niet aangeraakt, zich hierdoor anders zou kunnen gedragen. Die test laat sommige heel kleine wijzigingen toe en sluit sommige heel grote uit.</p> <p>Alles hieronder gaat ervan uit dat de aanroeper buiten het bedrijf zit en effectief niet bereikbaar is behalve via dit document. Wanneer de aanroeper een ander team binnen hetzelfde bedrijf is, verandert de afweging genoeg om een eigen behandeling te verdienen; <a href="https://changeloop.dev/blog/nl/internal-api-changelog/">interne API-changelogs</a> behandelt wat dat publiek in plaats daarvan nodig heeft.</p> <table> <thead> <tr> <th>Document</th> <th>Publiek</th> <th>Beantwoordt</th> </tr> </thead> <tbody><tr> <td>API-changelog</td> <td>Developers die de API aanroepen</td> <td>Werkt mijn integratie nog?</td> </tr> <tr> <td>Release notes</td> <td>Gebruikers van het product</td> <td>Wat kan ik nu wat ik eerder niet kon?</td> </tr> <tr> <td>Deprecation-melding</td> <td>Aanroepers van één specifiek ding</td> <td>Wanneer stopt dit met werken?</td> </tr> <tr> <td>Statuspagina</td> <td>Iedereen die nu getroffen is</td> <td>Ligt het er nu uit?</td> </tr> <tr> <td>Migratiegids</td> <td>Aanroepers die migreren</td> <td>Hoe kom ik van A naar B?</td> </tr> </tbody></table> <p><a href="https://changeloop.dev/blog/nl/api-migration-guide/">Hoe je een API-migratiegids schrijft</a> behandelt dat laatste document volledig; kort gezegd is het waar een breaking-change-regel naar zou moeten linken in plaats van het te proberen te vervangen.</p> <p>De vijf zijn aparte documenten met aparte levenscycli. Een deprecation-melding is een belofte met een datum, en hoort ook thuis in de changelog, maar een changelog-item wordt eenmaal geschreven terwijl een deprecation gevolgd wordt tot de sunset. Ze door elkaar halen is waarom sunsets gemist worden.</p> <h2>Wat hoort in één item?</h2> <p>Zes dingen, en de eerste drie zijn wat meestal ontbreekt. De wijziging, geformuleerd in termen van het verzoek of de respons in plaats van het interne component. Of het een correcte aanroeper breekt. Wat de aanroeper moet doen, inclusief "niets". De datum waarop het van kracht werd. De betrokken versie of versies. Een link naar de migratiegids als die bestaat.</p> <p>Een item dat zegt "accounts-endpoint verbeterd" faalt op alle zes. Een item dat zegt "het veld <code>accounts.type</code> geeft nu <code>individual</code> terug waar het eerder <code>personal</code> teruggaf; bestaande waarden blijven ongewijzigd voor accounts aangemaakt vóór 2 september; geen actie nodig tenzij je de string vergelijkt" beantwoordt alle zes in één zin.</p> <p>Categoriseer items op gevolg, niet op afdeling. Drie labels dragen bijna alle waarde: breaking, additive en fixed. <a href="https://semver.org/">Semantic Versioning</a> definieert de eerste twee al precies, en die definities lenen in plaats van eigen definities verzinnen betekent dat een lezer die semver kent jouw labels kent. <a href="https://keepachangelog.com/en/1.1.0/">Keep a Changelog</a> biedt een langere set als je die wilt, en de kernregel geldt hier sterker dan waar dan ook: het logboek is voor mensen, en een dump van commit-titels is dat niet.</p> <h2>Hoe verschilt een API-changelog van release notes?</h2> <p>Release notes beschrijven wat het product nu kan. Een API-changelog beschrijft wat het contract nu is. Hetzelfde uitgebrachte werk produceert vaak een item in beide, anders geformuleerd, omdat de publieken andere dingen nodig hebben: een nieuw exportformaat is een functie voor een gebruiker en een nieuwe enum-waarde voor een aanroeper die op dat veld schakelt.</p> <p>Het praktische gevolg is dat de twee niet dezelfde feed met andere styling kunnen zijn. Een aanroeper die zich abonneert op alles wat je uitbrengt, meldt zich uiteindelijk af, en mist dan de breaking change. Publiceer je één feed, filter hem dan; publiceer je er twee, maak de API-feed dan smaller en laat er nooit een marketingitem in. We vergelijken beide vormen naast elkaar in <a href="https://changeloop.dev/blog/nl/changelog-vs-release-notes/">changelog vs release notes</a>.</p> <h2>Waar moet een API-changelog leven?</h2> <p>Naast de referentiedocumentatie, op een stabiele URL, met elk item afzonderlijk adresseerbaar via een fragment of een eigen pad. Aanroepers linken naar items in incidentanalyses en interne tickets, en een item dat niet gelinkt kan worden, wordt in plaats daarvan als screenshot geplakt.</p> <p>Publiceer het ook als machineleesbare output, naast een pagina. Een JSON-feed volgens de <a href="https://www.jsonfeed.org/version/1.1/">JSON Feed-specificatie</a> of een <a href="https://www.rssboard.org/rss-specification">RSS-feed</a> kost niets zodra items gestructureerde data zijn, en het is wat een klant in staat stelt jouw wijzigingen in zijn eigen releaseproces op te nemen. Dit bepaalt ook of iemand erop voortbouwt. GitHub documenteert zijn <a href="https://docs.github.com/en/rest/about-the-rest-api/api-versions">REST API-versies</a> om dezelfde reden vlak naast de referentie: het versiebeleid maakt deel uit van de interface.</p> <h2>Hoe ziet een goed item er in de praktijk uit?</h2> <p>Drie items uit dezelfde week, in de hierboven beschreven vorm:</p> <pre><code>2026-09-02 Breaking v2 `POST /invoices` weigert nu een `currency` die niet overeenkomt met de accountvaluta van de klant, en geeft 422 terug in plaats van stil te converteren. Aanroepers die vertrouwden op conversie moeten de accountvaluta meesturen. Betreft alleen v2; v1 blijft ongewijzigd tot de sunset op 2027-01-15. 2026-09-02 Additive v1, v2 `Invoice` krijgt een `settled_at`-tijdstempel, null totdat de factuur betaald is. Geen actie nodig. Clients die onbekende velden weigeren, moeten worden bijgewerkt. 2026-08-31 Fixed v2 `GET /invoices?status=` gaf een lege pagina terug in plaats van een 400 bij een onbekende status. Geeft nu 400 terug met de geaccepteerde waarden. Aanroepers met een typefout zagen eerder nul resultaten, zien nu een fout. </code></pre> <p>De derde is het type dat het vaakst wordt weggelaten, omdat het intern een bugfix is. Voor een aanroeper die een retry rond die lege pagina had gebouwd, is het een gedragswijziging, en het item is wat het supportticket voorkomt. Het label zegt fixed en de body zegt wat een aanroeper zou kunnen opmerken, wat het onderscheid is dat het logboek eerlijk houdt zonder elke fix op te blazen tot breaking change.</p> <h2>Hoe abonneren aanroepers zich?</h2> <p>Geef ze meer dan één kanaal, want ze hebben andere taken. Een feed voor de developer die alles wil. E-mail voor wie alleen breaking changes wil. Response-headers voor de code zelf, de enige abonnee die nooit vergeet te controleren: de <a href="https://datatracker.ietf.org/doc/html/rfc8594"><code>Sunset</code>-header gedefinieerd in RFC 8594</a> plaatst de pensioendatum in de respons, waar een clientbibliotheek hem kan loggen.</p> <p>Het kanaal dat de meeste teams overslaan is het directe. Als een aanroeper vorige week het veld gebruikte dat je verandert, weet je wie hij is, en een e-mail naar die accounts is meer waard dan welke uitzending dan ook. Dit is dezelfde discipline als het <a href="https://changeloop.dev/blog/nl/customer-feedback-loop/">sluiten van de klantfeedbackloop</a>, toegepast op een wijziging die niemand heeft gevraagd: de betrokkenen worden individueel op de hoogte gebracht, en iedereen krijgt de feed. Een webhook is een vierde kanaal met een eigen faalpatroon dat het waard is te kennen voordat je erop vertrouwt: <a href="https://changeloop.dev/blog/nl/webhook-changelog/">webhook-changelogs</a> behandelt waarom een payloadwijziging daar stilletjes breekt, zonder aanroeper die de nieuwe vorm kan afwijzen.</p> <h2>Hoe schrijf je een item voor een breaking change?</h2> <p>Begin met de breuk, niet met de reden. Een aanroeper die tien items scant, moet in de eerste zin weten of deze hem werk gaat kosten. Dan de datum, de betrokken versies, de migratie, en de deadline als het oude gedrag verdwijnt in plaats van verandert.</p> <p>Zet dezelfde inhoud in de deprecation-melding, de response-header en de directe e-mail, consistent geformuleerd, en geef alle vier dezelfde datum. Afwijking daartussen is de fout die een geplande wijziging in een incident verandert, omdat de aanroeper die er maar één las op de verkeerde datum handelt. <a href="https://changeloop.dev/blog/nl/breaking-changes/">Wat is een breaking change</a> behandelt de beslissing zelf, en <a href="https://changeloop.dev/blog/nl/api-deprecation/">hoe deprecieer je een API</a> behandelt het tijdschema dat erop volgt.</p> <p>Bij changeloop wordt een API-wijziging een item zodra de pull request wordt gemerged, iemand het concept bewerkt en goedkeurt, en het item wordt gepubliceerd op de <a href="https://changeloop.dev/docs">feed en de widget</a> op hetzelfde moment dat een aanroeper wiens widgetfeedback het GitHub-issue werd dat de pull request sluit, daarover op dat issue op de hoogte wordt gebracht. De reviewstap is wat hier telt: een API-changelog is een contractueel document, en geen concept zou een aanroeper mogen bereiken zonder dat iemand het gelezen heeft.</p> <h2>FAQ</h2> <p><strong>Heeft elke API-wijziging een changelog-item nodig?</strong> Elke wijziging die een correcte aanroeper zou kunnen opmerken, ja, ook de wijzigingen die je intern vindt. Wijzigingen zonder observeerbaar effect op het verzoek of de respons niet, en die toevoegen traint lezers om te scannen zonder te lezen.</p> <p><strong>Moet de API-changelog in de docs staan of op de marketingsite?</strong> In de docs, vlak naast de referentie. De lezer is meestal al daar, en een changelog op de marketingsite krijgt vaak een publiek waarvoor hij niet geschreven is.</p> <p><strong>Hoe ver terug moet hij gaan?</strong> Onbeperkt. Items worden jaren later geciteerd in incidentanalyses, en een afgekapt logboek breekt die links. Pagineer in plaats van te snoeien.</p> <p><strong>Heb ik een aparte changelog per API-versie nodig?</strong> Nee, één logboek met een versieveld per item is makkelijker te lezen en te doorzoeken. Filteren op versie is een functie van de pagina, geen reden om het document te splitsen.</p> </article> <article> <h1>Een changelogpagina bouwen die mensen blijven volgen</h1> <p>Wed, 02 Sep 2026 00:00:00 GMT</p> <p>Een changelogpagina is de moeite van het bouwen waard als iemand erop zou terugkomen. Dat is een hogere lat dan er gewoon een hebben, en het is de lat waarop de meeste struikelen: een pagina die bestaat, gelinkt is in de footer, met horten en stoten wordt bijgewerkt en door niemand bezocht wordt behalve tijdens een incident. De beslissingen die de twee scheiden, worden genomen voordat er iets geschreven is, en gaan vooral over waar de pagina leeft en wat er nog meer uit dezelfde inhoud gegenereerd wordt.</p> <h2>Wat is een changelogpagina?</h2> <p>Het is de publieke, gedateerde lijst van wat er veranderd is in een product, op een URL die van jou is. Het is een van vijf oppervlakken waarop dezelfde items kunnen verschijnen, en de bruikbare vraag is niet welke je kiest maar welke canoniek is en welke ervan afgeleid worden.</p> <table> <thead> <tr> <th>Oppervlak</th> <th>Best voor</th> <th>Kosten</th> </tr> </thead> <tbody><tr> <td>Gehoste pagina</td> <td>Zoeken, linken, het lange overzicht</td> <td>Een URL en een template</td> </tr> <tr> <td>Widget in de app</td> <td>Gebruikers bereiken die de pagina nooit bezoeken</td> <td>Een embed, en terughoudendheid</td> </tr> <tr> <td>Docs-sectie</td> <td>API- en developerpubliek</td> <td>Naast de referentie houden</td> </tr> <tr> <td>JSON-feed</td> <td>Klanten die op je wijzigingen voortbouwen</td> <td>Structuur die je al hebt</td> </tr> <tr> <td>RSS-feed</td> <td>Developers die zich eenmaal abonneren</td> <td>Bijna niets</td> </tr> </tbody></table> <p>Kies één canonieke bron, publiceer eenmaal, en genereer de rest. Teams die de pagina en de widget apart met de hand onderhouden, eindigen met twee teksten die niet overeenkomen, en een klant ontdekt de discrepantie.</p> <h2>Waar moet een changelogpagina leven?</h2> <p>Op je eigen domein, op een stabiel pad, met elk item afzonderlijk adresseerbaar. De drie gebruikelijke plekken zijn een pad op de hoofdsite, een subdomein, en een sectie van de documentatie. Een pad op de hoofdsite is de standaardkeuze waartegen je moet argumenteren, niet voor: het erft het gezag van de site, heeft geen extra certificaat of DNS nodig, en houdt de pagina in dezelfde navigatie als al het andere.</p> <p>Een subdomein is het juiste antwoord als de pagina door een ander systeem wordt bediend dan de marketingsite en je anders zou proxyen. De kosten zijn dat het apart gezag opbouwt. De changelog in de docs zetten is juist als het publiek developers zijn, om de reden behandeld in <a href="https://changeloop.dev/blog/nl/api-changelog/">API-changelog</a>: de lezer is daar meestal al.</p> <p>Belangrijker dan de keuze is dat items afzonderlijk linkbaar zijn. Mensen linken naar items in incidentanalyses en interne tickets, en een item dat alleen als "de changelog, scroll naar beneden" gelinkt kan worden, wordt in plaats daarvan als screenshot geplakt.</p> <h2>Wat heeft een changelogpagina nodig?</h2> <p>Vijf dingen, en op de eerste twee falen de meeste pagina's. Een gedateerd item per wijziging, het nieuwste eerst. Een categorie of label per item om te kunnen scannen op het type dat je interesseert. Een permalink per item. Een abonneerroute. Een zoekfunctie of filter na ongeveer vijftig items.</p> <p>De rest is optioneel. Screenshots helpen en kosten onderhoud. Auteursnamen bouwen vertrouwen op bij sommige producten en zijn ruis bij andere. Versienummers zijn belangrijk voor aanroepers van een API en voor bijna niemand anders. <a href="https://keepachangelog.com/en/1.1.0/">Keep a Changelog</a> is een redelijke standaard voor labels als je geen reden hebt om eigen labels te verzinnen, en de kernregel is degene die je moet houden zelfs als je de rest weggooit: het logboek is geschreven voor mensen.</p> <p>Groepeer op datum in plaats van op versie als je product continu uitbrengt. Een lezer die scant "was dit voor of na ons incident op de negende" zoekt een datum, en een pagina georganiseerd op versienummer dwingt hem te rekenen.</p> <h2>Pagina of widget in de app?</h2> <p>Beide, uit één bron. De pagina is waar zoeken, links en het lange overzicht leven. De widget is hoe je de meerderheid van gebruikers bereikt die de pagina nooit zullen bezoeken, en werkt omdat hij verschijnt in het product dat ze al gebruiken.</p> <p>Het falen van de widget is onderbreking. Een badge die aandacht eist voor elk item wordt binnen een week permanent weggeklikt, wat je het kanaal kost voor het item dat er echt toe deed. Tel ongelezen sinds de laatste keer dat de lezer keek, zaai de teller stil bij het eerste bezoek zodat niemand begroet wordt met een badge van een jaar geschiedenis, en laat de lezer hem openen in plaats van hem voor hem te openen.</p> <h2>Hoe maak je een changelogpagina machineleesbaar?</h2> <p>Publiceer dezelfde items als feed. Een <a href="https://www.jsonfeed.org/version/1.1/">JSON-feed</a> is de optie met de minste wrijving voor alles wat het in code consumeert, en een <a href="https://www.rssboard.org/rss-specification">RSS-feed</a> is wat een developer die zich abonneert in een reader verwacht. Beide kosten weinig zodra items gestructureerde data zijn in plaats van met de hand geschreven HTML, wat het echte argument is om de canonieke kopie gestructureerd te houden.</p> <p>Markeer de pagina ook. Items zijn werken met een datum en een titel, en <a href="https://schema.org/CreativeWork">schema.org</a> levert de vocabulaire. Dat is de moeite waard om dezelfde reden als de permalinks: het maakt de pagina bruikbaar voor dingen die geen browser zijn, inclusief het eigen releaseproces van een klant. Niets hiervan werkt als de onderliggende items nooit gestructureerde data waren om te beginnen; <a href="https://changeloop.dev/blog/nl/changelog-file-formats/">changelog-bestandsformaten</a> behandelt wat Markdown, JSON en YAML elk kosten als de bron van waarheid waaruit deze feed en deze markup daadwerkelijk worden gegenereerd.</p> <h2>Helpt een changelogpagina de SEO?</h2> <p>Indirect en langzaam. Individuele items ranken zelden, omdat ze op geen enkele zoekopdracht mikken die iemand typt. De pagina verdient zijn plek via links: items worden geciteerd in supportantwoorden, forums en incidentanalyses, en die links stapelen zich op een URL die van jou is. Een pagina die twee jaar lang wekelijks wordt bijgewerkt, is ook een geloofwaardig versheidssignaal voor het product waartoe hij behoort.</p> <p>Wat niet werkt, is items behandelen als contentmarketing. Een item opgeblazen tot drie alinea's om het langer te maken, is slechter in zijn eigenlijke taak, namelijk een lezer in één zin vertellen of iets dat hij gebruikt veranderd is. Als je wilt dat de changelog zoeken ondersteunt, stop de moeite dan in de permalinks, de feed en de interne links ernaartoe, en houd de items kort. Onze eigen pagina met <a href="https://changeloop.dev/changelog-examples">changelogvoorbeelden</a> verzamelt pagina's die deze balans goed raken.</p> <h2>Hoe abonneren mensen zich?</h2> <p>Geef ze de routes die ze al gebruiken: een RSS- of JSON-feed voor developers, e-mail voor wie alleen de belangrijke dingen wil horen, en de widget in de app voor iedereen die geen van beide ooit zal doen. Vraag wat ze willen horen in plaats van het aan te nemen, want een lezer die breaking changes wil en tekstcorrecties krijgt, meldt zich af van beide.</p> <p>De route die je als laatste toevoegt, is degene die de loop sluit. Als een item oplost wat een specifieke persoon vroeg, vertel het hem dan direct in plaats van te hopen dat hij de pagina leest. Bij changeloop wordt het item in één keer gepubliceerd op de <a href="https://changeloop.dev/docs">pagina, de feed en de widget</a>, en een persoon wiens widgetfeedback het GitHub-issue werd dat de pull request sloot, wordt op dat issue op de hoogte gebracht met een link naar het item, en ziet het item in de widget. Het mechanisme is hetzelfde als elk abonnement; het verschil is dat de ontvanger al gevraagd heeft. Dat is het argument dat wordt uitgewerkt in <a href="https://changeloop.dev/blog/nl/customer-feedback-loop/">de feedbackloop sluiten vanuit de changelog</a>.</p> <h2>FAQ</h2> <p><strong>Moet de changelogpagina op een subdomein of een pad staan?</strong> Standaard een pad op de hoofdsite, want dat erft het gezag van de site en heeft geen extra infrastructuur nodig. Een subdomein is gerechtvaardigd als een ander systeem de pagina bedient.</p> <p><strong>Hoeveel items moet de pagina tegelijk tonen?</strong> Genoeg om een scherm te vullen en niet meer, met paginering daarna. Twee jaar geschiedenis in één document laden is traag en maakt het nieuwste item moeilijker te vinden.</p> <p><strong>Moeten oude items ooit verwijderd worden?</strong> Nee. Ze worden geciteerd van buiten je site en de links breken. Corrigeer een item ter plaatse met een notitie, en houd de URL levend.</p> <p><strong>Moet elke wijziging op de pagina verschijnen?</strong> Alleen degene die een gebruiker zou kunnen opmerken. Een pagina die interne refactors logt, traint lezers om te scannen zonder te lezen, en een gescande pagina faalt op de dag dat hij iets dringends draagt.</p> </article> <article> <h1>De product-update e-mailtemplate die gelezen wordt</h1> <p>Wed, 02 Sep 2026 00:00:00 GMT</p> <p>De product-update e-mail die gelezen wordt, is de e-mail die naar iemand is gestuurd die precies vroeg wat hij aankondigt. Al het andere concurreert met de rest van de inbox op interessantheid, een wedstrijd die een release-aankondiging de meeste weken verliest. Dat ene feit zou de vorm van de e-mail moeten bepalen voordat er een woord geformuleerd is: wie ontvangt hem, en wat deed die persoon om op de lijst te komen.</p> <h2>Wat is een product-update e-mail?</h2> <p>Het is een bericht dat bestaande gebruikers vertelt wat er veranderd is in een product dat ze al gebruiken. Er zijn vier verschillende soorten, en ze als één lijst behandelen is waarom openingsratio's dalen. Elke soort heeft een andere trigger, een ander publiek en een andere aanvaardbare frequentie.</p> <table> <thead> <tr> <th>Soort</th> <th>Trigger</th> <th>Publiek</th> <th>Frequentie</th> </tr> </thead> <tbody><tr> <td>Gerichte notificatie</td> <td>Iemands specifieke verzoek is uitgebracht</td> <td>Eén persoon</td> <td>Elke keer dat het gebeurt</td> </tr> <tr> <td>Breaking-change-melding</td> <td>Een wijziging die de lezer werk kost</td> <td>Alleen betrokken accounts</td> <td>Elke keer dat het gebeurt</td> </tr> <tr> <td>Digest</td> <td>Het verstrijken van de tijd</td> <td>Opt-in gebruikers</td> <td>Maandelijks maximaal</td> </tr> <tr> <td>Lanceringsaankondiging</td> <td>Een lancering die een onderbreking waard is</td> <td>Segment of iedereen</td> <td>Zeldzaam, en moet zeldzaam aanvoelen</td> </tr> </tbody></table> <p>De meeste teams bouwen alleen de derde, sturen die naar iedereen, en concluderen dat product-update e-mails niet werken. De eerste twee dragen bijna alle waarde, omdat de lezer een voorafgaande reden heeft om geïnteresseerd te zijn, en het bericht aankomt terwijl die reden nog leeft.</p> <p>Deze vier rijen zijn allemaal geschreven voor klanten. Sales, support en customer success moeten ook weten wat er uitkwam, meestal in een andere vorm dan deze vier; <a href="https://changeloop.dev/blog/nl/internal-release-notes/">interne release notes</a> behandelt wat dat document zou moeten zeggen en waarom het vóór de klantgerichte notitie moet uitkomen.</p> <p>E-mail is een van meerdere kanalen die een lanceringsaankondiging kan gebruiken, niet het enige. <a href="https://changeloop.dev/blog/nl/new-feature-announcement/">Hoe je een nieuwe feature aankondigt</a> behandelt de andere, en hoe je daartussen kiest op basis van hoe groot de feature echt is.</p> <h2>Wat gaat er in de template?</h2> <p>Zes blokken, in deze volgorde. Het eerste is degene die het vaakst ontbreekt en degene die het werk doet.</p> <pre><code>Onderwerp: <wat er veranderd is, in de woorden van de lezer> 1. Waarom je dit ontvangt "Je vroeg in maart om CSV-export." of "Je integratie roept /v1/invoices aan, dat verandert op 15 januari." 2. Wat er veranderd is Eén zin. Wat nu mogelijk is, of wat nu kapot gaat. 3. Wat je moet doen Vaak "niets". Zeg dat expliciet, laat het niet impliciet. 4. Waar je het ziet Een link naar het changelog-item, niet naar de homepage. 5. Wanneer De datum van uitgave, of vanaf wanneer het geldt. 6. Hoe je je afmeldt Eén klik, en direct gerespecteerd. </code></pre> <p>Blok 1 is het verschil tussen een bericht en een algemene uitzending. Een lezer die op de eerste regel te horen krijgt dat dit de oplossing is van iets wat hij persoonlijk heeft aangevraagd, leest de rest. Zonder dat blok zijn blokken 2 tot en met 5 een nieuwsbrief, hoe goed ook geschreven.</p> <p>Houd het geheel onder ongeveer 150 woorden. De e-mail is een verwijzing naar het changelog-item, en het item is waar detail thuishoort. Een e-mail die het hele item reproduceert, geeft de lezer geen reden om te klikken, en jou geen signaal of het iemand iets kon schelen.</p> <h2>Welke onderwerpregels werken?</h2> <p>Noem de wijziging, niet de release. "CSV-export is live" wint van "update van september" omdat het eerste een feit is dat de lezer kan beoordelen en het tweede een container is. Versienummers in het onderwerp zijn nuttig voor aanroepers van een API en ruis voor iedereen anders, weer een reden om de publieken te scheiden.</p> <p>Vermijd het beweren van een voordeel waarmee de lezer niet heeft ingestemd. "Je rapporten zijn nu sneller" beweert iets over zijn ervaring; "Rapporten van meer dan 10.000 rijen laden nu in minder dan een seconde" meldt een wijziging en laat hem beslissen of het ertoe doet.</p> <h2>Wanneer stuur je er een, en aan wie?</h2> <p>Stuur een gerichte notificatie op het moment dat het ding wordt uitgebracht, naar de mensen die het vroegen, individueel. Stuur een breaking-change-melding zodra de datum vaststaat en nog eens vlak ervoor, naar de daadwerkelijk betrokken accounts in plaats van de hele lijst. Stuur een digest alleen als je genoeg wijzigingen hebt dat een lezer anders iets zou missen, en laat mensen zich apart inschrijven.</p> <p>De lijst die je bijna nooit zou moeten gebruiken, is "alle gebruikers". Die verandert een specifiek bericht in een generiek bericht, en traint afmelding. Segmenteer op gedrag dat je al opslaat: wie erom vroeg, wie dit endpoint gebruikt, wie op dit plan zit.</p> <h2>Heb je toestemming nodig om hem te sturen?</h2> <p>Voor bestaande klanten is een update over een dienst die ze gebruiken meestal een andere juridische vraag dan marketing naar een prospect, en het antwoord hangt af van waar ze zich bevinden en wat je hun bij aanmelding hebt verteld. In de EU is de relevante vraag welke rechtsgrond uit <a href="https://gdpr-info.eu/art-6-gdpr/">artikel 6 van de AVG</a> van toepassing is, en in de Verenigde Staten dragen commerciële berichten specifieke eisen die zijn vastgelegd in de <a href="https://www.ftc.gov/business-guidance/resources/can-spam-act-compliance-guide-business">CAN-SPAM-nalevingsgids van de FTC</a>. Beide eisen in de praktijk hetzelfde: zeg wie je bent, maak het doel duidelijk, en laat mensen kunnen stoppen.</p> <p>Wat de grondslag ook is, houd transactionele en marketingstromen gescheiden op verzendniveau. Een breaking-change-melding waarvoor een klant zich heeft afgemeld omdat hij dezelfde lijst deelde met een promotionele digest, is een supportincident dat op zijn datum wacht.</p> <h2>Hoe ziet dit ingevuld eruit?</h2> <p>De gerichte notificatie, de meest waardevolle product-update e-mail en degene die de meeste teams nooit bouwen:</p> <pre><code>Onderwerp: CSV-export is live Hoi Dana, je vroeg in maart om CSV-export. Het is vanochtend live gegaan. Rapporten hebben nu een Exporteer-knop die een CSV van de huidige weergave genereert, filters inbegrepen. Niets te doen aan jouw kant. Het staat al aan voor je account. Details: example.com/changelog#csv-export Uitgebracht: 2 september 2026 Je ontvangt dit omdat je erom vroeg. Afmelden voor verzoek-updates: <link> </code></pre> <p>Negentig woorden, en de lezer weet op de eerste regel waarom dit aankwam. Vergelijk dit met dezelfde wijziging in een maandelijkse digest, waar hij verschijnt als een van de negen punten en Dana geen reden heeft om te merken dat haar eigen verzoek is uitgegaan.</p> <h2>Wat moet je meten?</h2> <p>Niet alleen de openingsratio. Voor een gerichte notificatie is de vraag of de persoon die vroeg terugkwam en het ding gebruikte, dus het getal om te volgen is de klik naar het item en of dat account de functie binnen een week gebruikt. Voor een breaking-change-melding is het dekking: welk aandeel betrokken accounts opende vóór de datum, en met wie je individueel hebt opgevolgd.</p> <p>Een digest is de enige van de vier waar een openingsratio veel betekent, en zelfs daar is hij nuttiger als trend tegen zijn eigen geschiedenis dan tegen een sectorbenchmark. Verschillende soorten product-update e-mails hebben verschillende taken, dus een gemiddeld cijfer over alle soorten beschrijft niets waarop je kunt handelen.</p> <h2>Hoe verschilt dit van release notes?</h2> <p>Release notes zijn een document dat beschikbaar blijft. De e-mail is een leveringsmechanisme dat eenmalig gebeurt. Dezelfde wijziging produceert beide, en de e-mail zou korter moeten zijn dan het item waarnaar hij verwijst. <a href="https://changeloop.dev/blog/nl/release-notes-best-practices/">Beste praktijken voor release notes</a> behandelt het document, en <a href="https://changeloop.dev/blog/nl/changelog-vs-release-notes/">changelog vs release notes</a> behandelt welke je aan het schrijven bent.</p> <p>De relatie die het waard is om goed te krijgen: het changelog-item is de canonieke tekst en de e-mail citeert hem. Wanneer die twee uit elkaar lopen, vindt de lezer die klikt een andere beschrijving van de wijziging en vertrouwt hij beide niet meer. Eerst het item publiceren en daaruit de e-mail genereren elimineert de afwijking door constructie. Changeloop werkt aan zijn kant op dezelfde manier: een item wordt eenmaal beoordeeld en gepubliceerd op de <a href="https://changeloop.dev/docs">pagina, de feed en de widget</a>, en de persoon die erom vroeg via de widget wordt op de hoogte gebracht op het GitHub-issue dat van haar feedback werd gemaakt, en in de widget zelf. Changeloop verstuurt de e-mail niet; je e-mailtool citeert het gepubliceerde item.</p> <h2>FAQ</h2> <p><strong>Hoe vaak moet een product-update e-mail uitgaan?</strong> Zo vaak als er iets specifieks is dat de ontvanger wil weten, wat voor een gerichte notificatie elke keer is dat zijn verzoek wordt uitgebracht en voor een digest maandelijks maximaal.</p> <p><strong>Moet de e-mail het hele changelog-item bevatten?</strong> Nee. Eén zin en een link. Het item is de canonieke versie, en een volledige kopie in de e-mail betekent twee teksten die op elkaar afgestemd moeten blijven.</p> <p><strong>Welke openingsratio moet ik verwachten?</strong> Vergelijk elke soort met zichzelf in plaats van met een benchmark. Een gerichte notificatie en een maandelijkse digest zijn verschillende producten, en ze middelen verbergt het enige cijfer dat de moeite waard is om te volgen.</p> <p><strong>Heb ik een aparte lijst nodig voor breaking changes?</strong> Ja, en het moet de lijst zijn waarvan mensen zich niet achteloos kunnen afmelden zonder het gevolg te begrijpen, want het is de lijst die hen een storing kost.</p> </article> <article> <h1>Hoe deprecieer je een API zonder developers te verliezen</h1> <p>Sat, 29 Aug 2026 00:00:00 GMT</p> <p>Een API deprecieren is aankondigen dat iets vandaag nog werkt en op een genoemde datum stopt met werken, en dan beide helften van die belofte houden. De meeste deprecaties falen op de tweede helft: de datum verschuift stilletjes, of hij komt en de aanroepers die de aankondiging nooit zagen horen het van een fout. Een deprecatie is af wanneer elke getroffen aanroeper is gemigreerd of, individueel, te horen heeft gekregen dat dat niet zo is.</p> <h2>Wat is API-deprecatie?</h2> <p>Deprecatie is de periode tussen het aankondigen dat een endpoint, veld of versie gaat verdwijnen en het daadwerkelijk verwijderen ervan. Tijdens die periode blijft het oude gedrag werken, zegt de documentatie dat het weggaat, en draagt elk antwoord een machineleesbare waarschuwing. Verwijdering is het aparte, latere moment, vaak sunset genoemd. De twee worden door elkaar gehaald, en die verwarring is waar de schade gebeurt: "deprecated" begint "misschien al weg" te betekenen, en aanroepers vertrouwen geen van beide woorden meer.</p> <table> <thead> <tr> <th>Term</th> <th>Betekenis</th> <th>Waar aanroepers op kunnen rekenen</th> </tr> </thead> <tbody><tr> <td>Deprecated</td> <td>Aangekondigd als verdwijnend, werkt nog</td> <td>Volledig gedrag tot de sunset-datum</td> </tr> <tr> <td>Sunset</td> <td>De datum waarop het stopt met werken</td> <td>Niets na deze datum</td> </tr> <tr> <td>Retired / verwijderd</td> <td>Weg; verzoeken falen</td> <td>Een fout, idealiter een die de vervanging noemt</td> </tr> <tr> <td>Legacy</td> <td>Ongedefinieerd. Vermijd het woord</td> <td>Niets, wat het probleem is</td> </tr> </tbody></table> <h2>Hoe lang zou een deprecatieperiode moeten duren?</h2> <p>Lang genoeg voor een aanroeper om erachter te komen en het werk te doen, gemeten vanaf wanneer de aankondiging hem bereikte in plaats van vanaf wanneer jullie hem schreven. Negentig dagen is de gangbare ondergrens voor een publieke web-API. Twaalf maanden is normaal voor alles wat is ingebed in software die eindgebruikers installeren, omdat de fix ook door hun releaseproces moet. Googles versioneringsrichtlijn, <a href="https://google.aip.dev/185">AIP-185</a>, vraagt om een redelijke overgangsperiode en raadt 180 dagen aan, zelfs voordat bètafunctionaliteit wordt verwijderd, en Kubernetes documenteert zijn <a href="https://kubernetes.io/docs/reference/using-api/deprecation-policy/">deprecatiebeleid</a> in aantal releases in plaats van maanden, wat de juiste eenheid is wanneer jullie aanroepers per versie updaten.</p> <p>Kies een periode, schrijf hem vast als beleid, en stop met hem per verandering te beslissen. Een gepubliceerd beleid maakt van elke deprecatie een regeltoepassing in plaats van een onderhandeling.</p> <p>Het deprecatiebeleid vastleggen dekt het begin van het venster; <a href="https://changeloop.dev/blog/nl/sunsetting-api-version/">een API-versie uitfaseren</a> behandelt het aparte bericht dat nodig is aan het einde, wanneer de periode daadwerkelijk afloopt en de versie stopt met werken.</p> <h2>Het deprecatieschema</h2> <p>Vier datums, samen op dag één aangekondigd. Elk is een aparte changelog-entry bij aankomst, dus het verhaal wordt vier keer verteld aan iedereen die alleen de changelog leest.</p> <ol> <li><strong>Aankondigen.</strong> De entry zegt wat wordt gedeprecieerd, waarom, wat het vervangt, en de sunset-datum. De documentatie voor het oude ding krijgt een banner die naar de migratie linkt. Antwoorden krijgen de hieronder beschreven headers.</li> <li><strong>Herinneren, halverwege.</strong> Een tweede entry, en een direct bericht aan elke aanroeper die het oude gedrag nog gebruikt. Dit is de stap die gebruiksdata nodig heeft: als jullie niet kunnen opsommen wie het gedeprecieerde endpoint nog aanroept, kunnen jullie het niet doen, en dat is de moeite waard om op te lossen voor de volgende deprecatie.</li> <li><strong>Brownout, kort voor de datum.</strong> Geef fouten terug voor het oude gedrag gedurende een kort venster, een uur of een dag, en herstel het dan. Aanroepers die elke aankondiging misten ontdekken het nu, terwijl er nog tijd is. GitHub gebruikte geplande brownouts voordat het <a href="https://github.blog/2020-07-30-token-authentication-requirements-for-api-and-git-operations/">wachtwoordauthenticatie voor de API afschafte</a>, en het is de effectiefste enkele stap in deze lijst.</li> <li><strong>Sunset.</strong> Verwijder het. De fout die het vervangt noemt de vervanging en linkt naar de migratiegids. Houd de fout lange tijd op zijn plek; een 404 vertelt een aanroeper niets.</li> </ol> <h2>Wat zou een deprecatiebericht moeten zeggen?</h2> <p>Een deprecatiebericht zegt wat weggaat, wanneer het stopt, wat in plaats daarvan te gebruiken, en wie het treft. Hier is de vorm, ingevuld:</p> <blockquote> <p><strong><code>GET /v1/reports/daily</code> is gedeprecieerd en stopt met werken op 1 maart 2027.</strong> Het wordt vervangen door <code>GET /v2/reports?granularity=day</code>, dat dezelfde data teruggeeft met een stabiel schema en paginering. Treft de 214 integraties die het v1-endpoint de afgelopen 30 dagen aanriepen; als de jouwe daar één van is, ontvang je dit bericht ook per e-mail. Migratiegids: [link]. Er verandert niets tot 1 maart 2027. Vanaf die datum geeft het v1-endpoint <code>410 Gone</code> terug met een link naar deze entry.</p> </blockquote> <p>Elke zin draagt iets waar de lezer behoefte aan heeft. Het aantal getroffen integraties vertelt elke lezer of ze moet blijven lezen. "Er verandert niets tot" is de zin die degenen die niet getroffen zijn het tabblad laat sluiten. De pagina <a href="https://changeloop.dev/changelog-examples">changelog-voorbeelden</a> verzamelt entries van teams die deze vorm consequent schrijven, en het is de moeite waard om er drie te lezen voordat je je eigen eerste schrijft.</p> <h2>Welke headers zou een gedeprecieerd endpoint moeten sturen?</h2> <p>Stuur <code>Deprecation</code>, <code>Sunset</code> en een <code>Link</code> naar de opvolger, op elk antwoord van het gedeprecieerde endpoint, vanaf de dag van de aankondiging. De <a href="https://datatracker.ietf.org/doc/html/rfc9745"><code>Deprecation</code>-header</a> draagt de datum waarop de deprecatie inging; de <a href="https://datatracker.ietf.org/doc/html/rfc8594"><code>Sunset</code>-header</a> draagt de datum waarop het endpoint stopt met antwoorden; <code>Link: <url>; rel="successor-version"</code> wijst naar wat in plaats daarvan te gebruiken.</p> <pre><code>HTTP/1.1 200 OK Deprecation: @1756425600 Sunset: Mon, 01 Mar 2027 00:00:00 GMT Link: <https://api.example.com/v2/reports>; rel="successor-version" Link: <https://example.com/changelog/daily-reports>; rel="deprecation" </code></pre> <p>De meeste aanroepers zullen de headers zelf nooit lezen. Hun waarde zit erin dat de HTTP-client, gateway of monitoring van een aanroeper dat wel kan, wat jullie deprecatie verandert in een alert aan hun kant in plaats van een pagina aan de jullie kant. SDK's die jullie leveren zouden een waarschuwing moeten loggen wanneer ze er een zien.</p> <h2>Wie is ingelicht, en hoe weten jullie dat?</h2> <p>Dit is de stap die beslist of de sunset rustig verloopt of een supportincident wordt, en het is de lastigste om alleen met een changelog te doen. Een changelog-entry licht iedereen in die de changelog leest. Een deprecatie moet de specifieke mensen bereiken wier code gaat falen, en de gebruikelijke manier om ze te vinden is dezelfde gebruiksdata die de halverwege-herinnering nodig heeft: de API-sleutels, apps of accounts die het gedeprecieerde gedrag recent aanriepen.</p> <p>De loop die wij draaien: de entry wordt opgesteld uit de pull request die de deprecatie toevoegt, een mens beoordeelt de formulering en de datum, en zodra hij is gepubliceerd is de entry zelf de notificatie. Iedereen wiens widgetfeedback over het probleem, of verzoek om de vervanging, een GitHub-issue werd dat de pull request sluit, krijgt een reactie op dat issue dat het is uitgebracht, met een link naar de entry. <a href="https://changeloop.dev/docs">Feed en widget</a> bedienen dezelfde entry aan iedereen anders, samen met elke andere entry in de <a href="https://changeloop.dev/blog/nl/api-changelog/">API-changelog</a>. Wat we niet doen is de deprecatie "uitgebracht" laten worden voordat een mens hem heeft gepubliceerd; een bericht met de verkeerde datum is erger dan geen bericht.</p> <p>Wat jullie tooling ook is, de vraag die je op sunset-dag moet kunnen beantwoorden is: welke aanroepers gebruikten dit vorige week nog, en wie van hen hebben we direct verteld? Als het antwoord "we hebben erover gepost" is, is de sunset niet klaar.</p> <h2>Wat is het verschil tussen deprecieren en versioneren?</h2> <p>Versioneren is hoe je het oude gedrag beschikbaar houdt terwijl het nieuwe bestaat; deprecatie is hoe je het oude met pensioen stuurt. Een nieuwe API-versie zonder deprecatiebeleid voor de vorige is een belofte om beide voor altijd te draaien. Een deprecatie zonder versionering is een <a href="https://changeloop.dev/blog/nl/breaking-changes/">breaking change</a> met vertraging. Jullie hebben beide nodig, en de versie is de makkelijkere helft. GraphQL is de uitzondering die het waard is om te noemen: meestal is er helemaal geen versienummer om te verhogen, en <a href="https://changeloop.dev/blog/nl/graphql-schema-deprecation/">GraphQL-schemadeprecatie</a> behandelt hoe één gedeeld schema in plaats daarvan een veld met een directive met pensioen stuurt.</p> <h2>FAQ</h2> <p><strong>Zou een gedeprecieerd endpoint precies zo moeten blijven werken als voorheen?</strong> Ja, tot de sunset-datum. De enige toegestane veranderingen zijn de toegevoegde headers en, tegen het eind, een geplande brownout die jullie van tevoren aankondigden.</p> <p><strong>Welke statuscode zou een met pensioen gestuurd endpoint moeten teruggeven?</strong> <code>410 Gone</code>, met een body en een <code>Link</code>-header naar de vervanging en de changelog-entry. <code>404</code> zegt dat de URL nooit heeft bestaan, wat onwaar en onbehulpzaam is.</p> <p><strong>Kan een deprecatieperiode worden ingekort?</strong> Alleen voor security. Als het oude gedrag uitbuitbaar is, zeg dat, kort de periode in, en vertel elke getroffen aanroeper direct in plaats van te vertrouwen op de changelog.</p> <p><strong>Moet ik een veld deprecieren, of alleen hele endpoints?</strong> Velden, parameters, enum-waarden, standaardwaarden en headers hebben allemaal dezelfde behandeling nodig, omdat elk een correcte aanroeper kan breken. Een verwijderd veld is de meest voorkomende deprecatie en de meest overgeslagen.</p> </article> <article> <h1>Beste practices voor API-versionering, voor aanroepers</h1> <p>Sat, 29 Aug 2026 00:00:00 GMT</p> <p>API-versionering is de praktijk om een oud contract werkend te houden nadat je het hebt veranderd, zodat aanroepers op hun eigen schema kunnen overstappen in plaats van op het jouwe. Die zin bevat de twee beslissingen die ertoe doen: wat telt als het contract veranderen, en hoelang het oude blijft werken. Waar het versienummer leeft, waar de meeste versioneringsdiscussies over gaan, is de minst belangrijke van de drie en de makkelijkste om goed te krijgen.</p> <h2>Wanneer zou je een API moeten versioneren?</h2> <p>Versioneer een API alleen wanneer een verandering een correcte aanroeper zou breken. Additieve veranderingen, nieuwe velden, nieuwe endpoints, nieuwe optionele parameters, hebben geen versie nodig; aanroepers geschreven tegen het oude contract blijven werken en de nieuwe mogelijkheid is er gewoon. Een <a href="https://changeloop.dev/blog/nl/breaking-changes/">breaking change</a> heeft er wel een nodig, want het alternatief is dat een aanroeper het van een fout verneemt. Elke release versioneren, ook de additieve, leert aanroepers dat versies ruis zijn, en ze stoppen met de berichten te lezen die ertoe doen.</p> <p>De praktische test is dezelfde als in het artikel over breaking changes: als een aanroeper die alleen op gedocumenteerd gedrag vertrouwde iets moet veranderen om te blijven werken, heeft de verandering een versie nodig. Zo niet, breng het uit onder de huidige versie en schrijf een changelog-entry.</p> <h2>Welk API-versioneringsschema zou je moeten gebruiken?</h2> <p>Gebruik het schema dat jullie aanroepers het makkelijkst kunnen zien en instellen, wat voor de meeste publieke API's een versie in het URL-pad of een gedateerde versie-header is. De vier gangbare schema's verschillen minder in mogelijkheden dan in wat ze van de aanroeper vragen, en dat is de juiste basis om te kiezen.</p> <table> <thead> <tr> <th>Schema</th> <th>Voorbeeld</th> <th>Wat de aanroeper moet doen</th> <th>Wie het gebruikt</th> </tr> </thead> <tbody><tr> <td>URL-pad</td> <td><code>/v2/invoices</code></td> <td>De URL veranderen bij het migreren</td> <td>De meeste publieke REST-API's</td> </tr> <tr> <td>Versie-header</td> <td><code>X-GitHub-Api-Version: 2022-11-28</code></td> <td>Een header sturen, of de standaard accepteren</td> <td>GitHub</td> </tr> <tr> <td>Gedateerde accountversie</td> <td><code>Stripe-Version: 2026-08-26</code></td> <td>Een datum vastzetten per verzoek of per account</td> <td>Stripe</td> </tr> <tr> <td>Queryparameter</td> <td><code>/invoices?version=2</code></td> <td>Een parameter toevoegen</td> <td>Oudere API's; nu zelden gekozen</td> </tr> <tr> <td>Mediatype</td> <td><code>Accept: application/vnd.example.v2+json</code></td> <td>Contenttypes onderhandelen</td> <td>Puristen; weinig aanroepers beheersen dit</td> </tr> </tbody></table> <p><strong>URL-pad</strong> is het meest zichtbaar en het minst flexibel. Elke aanroeper kan zien in welke versie hij zit door een logregel te lezen, en een versiesprong is een zoek-en-vervang. De kosten: het hele oppervlak verschuift ineens, je kunt het contract van één endpoint niet veranderen zonder een nieuwe versie te slaan voor alle, dus URL-versies zijn doorgaans zeldzaam en groot.</p> <p><strong>Versie-header</strong> houdt URL's stabiel en laat de server een standaard kiezen voor aanroepers die niets sturen, zoals <a href="https://docs.github.com/en/rest/about-the-rest-api/api-versions">GitHubs REST-API-versionering</a> werkt: een op datum genoemde versie in <code>X-GitHub-Api-Version</code>, met de oudst ondersteunde versie als standaard zodat ongeversioneerde aanroepers niet breken. De kosten: de versie is onzichtbaar in een URL en makkelijk te vergeten in een nieuwe client.</p> <p><strong>Gedateerde accountversie</strong> is het header-schema plus één toevoeging: de versie wordt tegen het account opgeslagen, zodat elk verzoek hem krijgt zonder iets te sturen. <a href="https://docs.stripe.com/api/versioning">Stripes API-versionering</a> zet elk account vast op de versie waarmee het is aangemaakt en laat een verzoek dat overschrijven met <code>Stripe-Version</code>. Dit is het aanroeper-vriendelijkste schema en het meeste werk om te draaien, omdat de server moet vertalen tussen elke ondersteunde versie en de huidige.</p> <p><strong>Queryparameter</strong> en <strong>mediatype</strong> werken beide en falen beide de zichtbaarheidstest op andere wijze: een queryparameter valt makkelijk weg bij het bouwen van een URL, en een mediatype-versie is onzichtbaar voor bijna elke tool waarmee een aanroeper debugt. Het datumschema van Stripe is het bekendste voorbeeld van de datumaanpak, en <a href="https://changeloop.dev/blog/nl/stripe-api-versioning/">hoe Stripe zijn API versioneert</a> loopt het door.</p> <h2>Hoe doe je API-versionering in de praktijk?</h2> <p>In de praktijk is een versie een genoemde set gedragingen, en de server mapt elk verzoek op één daarvan. De stappen zijn hetzelfde ongeacht welk schema de naam draagt.</p> <ol> <li><strong>Benoem versies op datum of geheel getal, niet op semantische versie.</strong> Een web-API is geen pakket. Aanroepers kunnen geen minor-versie van een URL vastpinnen, dus <code>v2</code> of <code>2026-08-26</code> zegt alles wat een aanroeper nodig heeft, en <a href="https://semver.org/">semantische versionering</a> impliceert een compatibiliteitsbelofte die het schema niet kan nakomen.</li> <li><strong>Houd de versie buiten de codepaden die zich er niet om bekommeren.</strong> Een versie zou aan de rand een vertaallaag moeten kiezen, niet de bedrijfslogica splitsen. Twee volledige kopieën van de codebase is hoe een versie onderhoudbaar wordt.</li> <li><strong>Geef elke versie een standaard en een document.</strong> Aanroepers die geen versie sturen krijgen de oudst ondersteunde, nooit de nieuwste, zodat een niet-vastgepinde client niet breekt op releasedag. Elke versie heeft een pagina die zegt wat er is veranderd ten opzichte van de vorige.</li> <li><strong>Stel een supportvenster in en publiceer het.</strong> Googles versioneringsrichtlijn, <a href="https://google.aip.dev/185">AIP-185</a>, vraagt om een redelijke, goed gecommuniceerde overgangsperiode en raadt 180 dagen aan, zelfs voor bètafunctionaliteit. Kies een venster, schrijf het op, en pas het toe zonder per versie opnieuw te onderhandelen.</li> <li><strong>Trek versies met pensioen zoals je endpoints met pensioen trekt.</strong> Een versie voorbij zijn venster krijgt dezelfde behandeling als elke <a href="https://changeloop.dev/blog/nl/api-deprecation/">gedeprecieerde API</a>: een aankondiging, een <code>Sunset</code>-header (<a href="https://datatracker.ietf.org/doc/html/rfc8594">RFC 8594</a>) op elk antwoord, een halverwege-herinnering aan de overgebleven aanroepers, en een verwijderdatum die standhoudt.</li> </ol> <h2>Wat zijn v1 en v2 in een REST-API?</h2> <p><code>v1</code> en <code>v2</code> zijn namen voor twee contracten die dezelfde server tegelijk ondersteunt. Een <code>v2</code> bestaat omdat iets in <code>v1</code> niet kon worden veranderd zonder zijn aanroepers te breken, dus ging de verandering in een nieuw contract en bleef het oude werken. De nummers impliceren niet dat <code>v2</code> compleet is of dat <code>v1</code> dood is; beide zijn alleen waar als de documentatie het zegt. Een <code>v3</code> die elk kwartaal verschijnt is een teken dat additieve veranderingen worden geversioneerd, of dat het contract nooit ontworpen was om verandering op te vangen. gRPC lost hetzelfde probleem anders op: <a href="https://changeloop.dev/blog/nl/grpc-protobuf-api-changes/">gRPC- en Protobuf-API-wijzigingen</a> behandelt versionering via de packagenaam in een <code>.proto</code>-bestand in plaats van een URL-pad, en een wire-formaat waar een veld hernoemen gratis is maar hernummeren een breaking change die geen enkele REST-aanroeper als riskant zou herkennen.</p> <h2>Wat zou een versieverandering moeten aankondigen?</h2> <p>Een versieverandering zou moeten aankondigen wat breekt, wie het treft, hoe te migreren, en hoelang de vorige versie blijft werken. De entry heeft dezelfde vorm als elke andere breaking-change-entry, plus één regel met het supportvenster. Hier is er een voor een header-geversioneerde API:</p> <blockquote> <p><strong>API-versie 2026-11-01 is beschikbaar. Versie 2025-06-15 wordt ondersteund tot 1 november 2027.</strong> Nieuw in 2026-11-01: <code>GET /invoices</code> geeft <code>amount</code> in kleinste eenheden terug als geheel getal in plaats van decimale string, en het gedeprecieerde veld <code>customer_name</code> wordt verwijderd ten gunste van het <code>customer</code>-object. Treft aanroepers op 2025-06-15 die <code>amount</code> als string parsen, wat de standaard is voor niet-vastgepinde clients aangemaakt voor juni 2025. Migratie: parse <code>amount</code> als geheel getal en lees de naam uit <code>customer.name</code>. Pin <code>X-Api-Version: 2026-11-01</code> wanneer je klaar bent. Er verandert niets voor aanroepers die geen versie vastpinnen.</p> </blockquote> <p>De laatste zin is degene die de meeste lezers laat stoppen met lezen, en hoort thuis in elke versieaankondiging. De pagina <a href="https://changeloop.dev/changelog-examples">changelog-voorbeelden</a> bevat entries van API's die zo versioneren, en het verschil tussen de goede en de rest zit meestal in die laatste zin.</p> <h2>Wie wordt ingelicht wanneer een versie verandert?</h2> <p>Iedereen op de oude versie, individueel, en de changelog voor iedereen anders. Een versieverandering is het enige geval waarin "we hebben erover gepost" gegarandeerd precies de aanroepers mist die ertoe doen: degenen die twee jaar geleden een versie vastpinden en sindsdien geen release notes meer hebben gelezen. Gebruiksdata beantwoordt wie zij zijn; het bericht moet ze bereiken waar hun code is, in de response-headers en in een bericht aan de accounteigenaar.</p> <p>In de loop die wij draaien wordt de entry die een versie aankondigt opgesteld uit de pull request die hem uitbrengt, beoordeeld door een mens, en gepubliceerd op <a href="https://changeloop.dev/docs">feed en widget</a>, waar een geversioneerde client hem als JSON kan lezen. Iedereen wiens widgetfeedback om de verandering vroeg, of de bug meldde die het oplost, en een GitHub-issue werd dat de pull request sluit, wordt ingelicht op dat issue zodra de entry live gaat. Het mechanisme is hetzelfde als voor elke entry; een versiesprong is gewoon de entry met de hoogste inzet.</p> <h2>FAQ</h2> <p><strong>Zou elke API-verandering een nieuwe versie moeten krijgen?</strong> Nee. Alleen breaking changes. Additieve veranderingen worden uitgebracht onder de huidige versie met een changelog-entry. Additieve veranderingen versioneren traint aanroepers om versies te negeren.</p> <p><strong>Is URL-versionering beter dan header-versionering?</strong> URL-versionering is makkelijker te zien voor aanroepers en moeilijker voor jou om stukje bij beetje te laten evolueren; header-versionering is andersom. Voor een publieke API met veel kleine clients faalt URL-versionering minder vaak. Voor een grote API met vertaallaag schaalt de gedateerde header-versie beter.</p> <p><strong>Hoeveel versies zouden tegelijk ondersteund moeten worden?</strong> Zo weinig als jullie supportvenster toelaat, en nooit een onbeperkt aantal. Twee of drie parallelle versies is normaal; meer dan dat betekent meestal dat versies niet worden ingetrokken.</p> <p><strong>Wat zouden niet-geversioneerde verzoeken moeten krijgen?</strong> De oudst ondersteunde versie, zodat bestaande niet-vastgepinde clients blijven werken, met een response-header die ze vertelt welke versie ze ontvingen.</p> </article> <article> <h1>Breaking changes: wat telt en hoe je er een uitbrengt</h1> <p>Sat, 29 Aug 2026 00:00:00 GMT</p> <p>Een breaking change is een verandering die een correct geschreven aanroeper niet had kunnen overleven. De definitie is belangrijk omdat de meeste discussies over of iets "telt" eigenlijk discussies zijn over wie het verkeerd vasthield. Als een aanroeper jullie documentatie volgde en jullie verandering zorgde dat zijn code ophield te werken, was de verandering breaking. Wat jullie bedoelden heeft daar niets mee te maken.</p> <p>Dat is de hele test. De rest van dit artikel is wat daaruit voortvloeit: wat de test niet doorstaat, wat hem wel doorstaat, hoe je een falen vangt voordat het wordt gemerged, en wat je doet zodra je weet dat je er een uitbrengt.</p> <h2>Wat telt als een breaking change?</h2> <p>Pas de test toe op de aanroeper, niet op de diff. Een verandering is breaking wanneer een aanroeper die alleen op gedocumenteerd gedrag vertrouwde zijn code, configuratie of data moet aanpassen om te blijven werken. Een veld verwijderen, een endpoint hernoemen, validatie aanscherpen, een standaardwaarde veranderen en het type van een waarde veranderen kwalificeren allemaal. Een optioneel veld toevoegen niet. Een bug fixen meestal niet, met één belangrijke uitzondering hieronder.</p> <table> <thead> <tr> <th>Verandering</th> <th>Breaking?</th> <th>Waarom</th> </tr> </thead> <tbody><tr> <td>Veld, endpoint, flag of optie verwijderen of hernoemen</td> <td>Ja</td> <td>Correcte aanroepers verwijzen ernaar</td> </tr> <tr> <td>Optioneel veld of nieuw endpoint toevoegen</td> <td>Nee</td> <td>Bestaande calls veranderen niet</td> </tr> <tr> <td>Optionele input verplicht maken</td> <td>Ja</td> <td>Calls die het weglieten falen nu</td> </tr> <tr> <td>Eerder geaccepteerde validatie aanscherpen</td> <td>Ja</td> <td>Input die werkte wordt nu geweigerd</td> </tr> <tr> <td>Een standaardwaarde veranderen</td> <td>Ja</td> <td>Aanroepers die hem niet instelden krijgen nieuw gedrag</td> </tr> <tr> <td>Een type veranderen (string naar getal, enkele waarde naar array)</td> <td>Ja</td> <td>Parsers geschreven voor het gedocumenteerde type falen</td> </tr> <tr> <td>Sleutels van een object herordenen</td> <td>Nee</td> <td>Tenzij jullie de volgorde documenteerden</td> </tr> <tr> <td>Een bug fixen waar aanroepers op vertrouwden</td> <td>In de praktijk ja</td> <td>Zie de sectie over toevallige contracten</td> </tr> <tr> <td>Een ratelimiet of groottelimiet verhogen</td> <td>Nee</td> <td>Niets wat werkte stopt met werken</td> </tr> <tr> <td>Een ratelimiet of groottelimiet verlagen</td> <td>Ja</td> <td>Verkeer dat prima was wordt nu beperkt</td> </tr> <tr> <td>De formulering van een foutmelding veranderen</td> <td>Hangt ervan af</td> <td>Breaking als jullie het documenteerden of aanroepers erop matchen</td> </tr> </tbody></table> <h2>Wat is geen breaking change?</h2> <p>Een verandering is niet-breaking wanneer elke call die eerder werkte nog steeds werkt, ongewijzigd, en nog steeds hetzelfde betekent. Een nieuw endpoint toevoegen, een optionele requestparameter toevoegen, een veld aan een antwoord toevoegen, een verplichte input optioneel maken, een limiet verhogen en een foutmelding verbeteren waar niemand op matcht doorstaan allemaal de test. Deze additieve veranderingen kunnen in een minor release met een gewone changelog-entry.</p> <p>Additieve veranderingen breken aanroepers toch in drie situaties. Een client waarvan de deserializer onbekende velden weigert, faalt op het eerste nieuwe antwoordveld, dus leg vroeg vast dat aanroepers velden die ze niet kennen moeten negeren. Een nieuwe enum-waarde breekt elke aanroeper met een uitputtende switch (daarover straks meer). En een antwoord dat groeit kan een aanroeper voorbij een groottelimiet, een timeout of een kolombreedte duwen waar hij nooit over hoefde na te denken.</p> <p>Vier rijen van de tabel verdienen een nadere blik, omdat daar de meningsverschillen ontstaan.</p> <h2>De vier breaking changes die teams missen</h2> <p><strong>Toevallige contracten.</strong> Als jullie API drie jaar hetzelfde ongedocumenteerde veld heeft teruggegeven, heeft een aanroeper erop gebouwd. <a href="https://www.hyrumslaw.com/">De wet van Hyrum</a> is de korte versie: met genoeg gebruikers zal elk waarneembaar gedrag van jullie systeem afhankelijk zijn voor iemand. Daarom is "het was een bugfix" geen verdediging. De fix kan correct zijn en toch breaking. Breng hem als zodanig uit.</p> <p><strong>Gedragsveranderingen zonder schemaverandering.</strong> Het veld is er nog, het type is hetzelfde, en de waarde betekent nu iets anders. Een <code>status</code> die vroeger <code>active</code> of <code>inactive</code> was en nu ook <code>suspended</code> teruggeeft breekt elke aanroeper met een uitputtende switch. Een timestamp die overgaat van lokale tijd naar UTC breekt iedereen die de docs niet twee keer las. Niets in een diff van het OpenAPI-bestand toont dit.</p> <p><strong>Aangescherpte validatie.</strong> Jullie beginnen e-mails zonder TLD te weigeren, of achterloopwitruimte, of namen langer dan 80 tekens. Elke aanroeper die precies dat verstuurde krijgt nu een 400 voor een verzoek dat vorige week werkte. Validatieveranderingen worden het vaakst uitgebracht als een "hardening"-fix.</p> <p><strong>Veranderde standaardwaarden.</strong> Niemand die de waarde expliciet instelde merkt iets. Iedereen die dat niet deed, wat de meeste aanroepers zijn, krijgt nieuw gedrag zonder een regel te veranderen. Een veranderde standaardwaarde breekt de meerderheid van jullie gebruikers precies omdat ze de instelling nooit hebben gezien.</p> <h2>Hoe ontdek je een breaking change voordat hij live gaat?</h2> <p>Vergelijk in CI het contract van de pull request met het contract van de hoofdbranch, en laat de build falen bij een breaking verschil. Voor de meeste interfaceformaten bestaan schema-diff-tools, en elk kent de breaking-regels van zijn eigen formaat:</p> <table> <thead> <tr> <th>Interface</th> <th>Tool</th> <th>Wat het vergelijkt</th> </tr> </thead> <tbody><tr> <td>REST (OpenAPI)</td> <td><a href="https://github.com/oasdiff/oasdiff">oasdiff</a></td> <td>Twee OpenAPI-specs, met een rapport over breaking changes</td> </tr> <tr> <td>gRPC (Protobuf)</td> <td><a href="https://buf.build/docs/breaking/">buf breaking</a></td> <td><code>.proto</code>-bestanden, op wire- of bronniveau</td> </tr> <tr> <td>GraphQL</td> <td><a href="https://github.com/kamilkisiela/graphql-inspector">GraphQL Inspector</a></td> <td>Twee schema's, met markering van breaking en gevaarlijke veranderingen</td> </tr> <tr> <td>Rust-crates</td> <td><a href="https://github.com/obi1kenobi/cargo-semver-checks">cargo-semver-checks</a></td> <td>De publieke API tegen de laatst gepubliceerde versie</td> </tr> <tr> <td>TypeScript-pakketten</td> <td><a href="https://api-extractor.com/">API Extractor</a></td> <td>Een gecommit rapport van de publieke API van het pakket</td> </tr> </tbody></table> <p>Deze tools vangen verwijderde velden, hernoemde operaties en veranderde types betrouwbaar. De eerste twee van de vier soorten hierboven, een toevallig contract en een gedragsverandering, zien ze niet, omdat geen van beide in een schema verschijnt. Gebruik de tool om de voor de hand liggende te stoppen en de reviewvraag "kan een correcte aanroeper dit merken?" voor de rest. Dezelfde CI-job is een natuurlijke plek om een changelog-entry te eisen, zoals beschreven in <a href="https://changeloop.dev/blog/nl/changelog-ci-enforcement/">changelog-entries afdwingen in CI</a>, en <a href="https://changeloop.dev/blog/nl/grpc-protobuf-api-changes/">gRPC- en Protobuf-API-veranderingen</a> loopt de gevallen op wire-niveau door.</p> <h2>Hoe markeer je een breaking change in een commit?</h2> <p>Met <a href="https://www.conventionalcommits.org/en/v1.0.0/">Conventional Commits</a> markeer je een breaking change met een <code>!</code> voor de dubbele punt (<code>feat(api)!: remove the legacy export endpoint</code>) of met een footer die begint met <code>BREAKING CHANGE:</code> gevolgd door een beschrijving. Beide leiden tot een majorversie. Schrijf de footer als eerste concept van de changelog-entry, met wie het treft en wat ze moeten doen. <a href="https://changeloop.dev/blog/nl/conventional-commits-changelog/">Conventional commits en de changelog</a> behandelt hoe ver de conventie je brengt.</p> <p>Dezelfde regel geldt voor bibliotheken. Een verwijderde publieke functie, een versmald parametertype of een veranderde returnwaarde is een majorversie onder semantische versionering. Bibliotheken volgen dat niet altijd: een <a href="https://arxiv.org/abs/2110.07889">studie van 119.879 Maven Central-upgrades</a> vond dat 16,6% de semantische versionering brak, maar slechts 7,9% van de clientprojecten werd getroffen, omdat de meeste van die veranderingen code raakten die geen client aanriep. Breuk wordt gemeten bij de aanroeper.</p> <h2>Hoe breng je een breaking change uit?</h2> <p>Je brengt hem openlijk uit, met een datum, met een pad. De stappen hieronder staan in volgorde, en de laatste is degene die de meeste teams overslaan: de mensen die getroffen werden vertellen dat waar ze op wachtten nu is gebeurd.</p> <ol> <li><strong>Beslis of het er een is.</strong> Gebruik de test hierboven, niet de diff. Als twee engineers het oneens zijn, is het breaking; het oneens-zijn is bewijs dat een aanroeper redelijkerwijs op het oude gedrag had kunnen vertrouwen.</li> <li><strong>Versioneer het.</strong> Onder <a href="https://semver.org/">semantische versionering</a> is een breaking change een majorversie. Als jullie een gedateerde of geversioneerde API draaien, gaat het in een nieuwe versie en blijft de oude werken tot een genoemde datum. Als jullie niet kunnen versioneren, brengen jullie geen breaking change uit, jullie brengen een storing uit met een changelog-entry. Welk schema de versie draagt is het onderwerp van <a href="https://changeloop.dev/blog/nl/api-versioning-best-practices/">beste practices voor API-versionering</a>.</li> <li><strong>Schrijf de entry voordat de code wordt gemerged.</strong> De entry heeft een vaste vorm: wat verandert, wie het treft, wat ze moeten doen, en tegen wanneer. Als jullie niet alle vier kunnen invullen, is de verandering niet klaar. De <a href="https://changeloop.dev/release-notes-template">release notes template</a> zet deze entries vooraan, met een datum in plaats van een versienummer, precies hierom.</li> <li><strong>Geef een deadline, geen releasenummer.</strong> "Verwijderd in v5" betekent niets voor iemand die jullie releases niet volgt. "Werkt niet meer vanaf 1 november 2026" betekent voor iedereen hetzelfde.</li> <li><strong>Lever de migratie mee.</strong> De oude call naast de nieuwe. Bij een hernoeming noem je beide namen in dezelfde zin; bij een verwijderd veld zeg je waar de data heen ging.</li> <li><strong>Kondig het overal aan waar het oude gedrag was gedocumenteerd.</strong> De changelog, de docspagina die het endpoint beschrijft, de release notes van de SDK, en de deprecatie-header in het antwoord als jullie die hebben.</li> <li><strong>Sluit de loop.</strong> Als een klant om de verandering vroeg, of de bug meldde die ertoe leidde, vertel het haar wanneer het uitkomt.</li> </ol> <h2>Hoe ziet een goede breaking-change-entry eruit?</h2> <p>Een goede entry noemt de getroffen aanroeper in de eerste regel, vermeldt de datum, en bevat de fix. Hier is er een voor het geval van aangescherpte validatie, in de vorm die wij gebruiken:</p> <blockquote> <p><strong>E-mailadressen zonder domein worden geweigerd vanaf 1 november 2026.</strong> <code>POST /users</code> en <code>PATCH /users/:id</code> accepteren momenteel <code>email</code>-waarden zoals <code>alice@localhost</code>. Vanaf 1 november geven deze <code>400 invalid_email</code> terug. Treft elke integratie die gebruikers aanmaakt vanuit interne directories. Migratie: stuur een volledig gekwalificeerd adres, of laat het veld weg en stel het later in. Geen verandering nodig als jullie adressen al een domein hebben, wat waar is voor 99,4% van de dit jaar aangemaakte accounts.</p> </blockquote> <p>Waar die melding thuishoort, en wat er nog meer naast moet staan, behandelt de <a href="https://changeloop.dev/blog/nl/api-changelog/">API-changelog</a>.</p> <p>Het percentage aan het eind is geen decoratie. Het vertelt de lezer of ze zich zorgen moet maken, wat de vraag is waarmee ze de entry opende.</p> <h2>Waarom ze niet gewoon vermijden?</h2> <p>Omdat het alternatief erger is. Een API die nooit iets breekt stapelt elke fout op die hij ooit maakte: het verkeerd benoemde veld, de foute standaardwaarde, de timestamp in lokale tijd. Elk daarvan is een belasting voor elke nieuwe aanroeper voor altijd, om aanroepers te beschermen die in een middag hadden kunnen migreren. De teams met de beste reputatie voor stabiliteit breken dingen zelden, volgens een schema, met een migratiepad en een waarschuwing die de mensen bereikte voor wie het bedoeld was.</p> <p>De mechaniek van die waarschuwing is het onderwerp van het begeleidende artikel over <a href="https://changeloop.dev/blog/nl/api-deprecation/">een API deprecieren</a>. De entry die het aankondigt wordt op dezelfde manier opgesteld als elke andere entry in de <a href="https://changeloop.dev/docs">changelog-feed</a>: uit de gemergede pull request, vastgehouden voor een mens, dan gepubliceerd op de plek waar de getroffen aanroepers al lezen.</p> <h2>FAQ</h2> <p><strong>Wat is het verschil tussen een breaking en een niet-breaking change?</strong> Een breaking change dwingt een correcte aanroeper zijn code, configuratie of data aan te passen om te blijven werken. Een niet-breaking change laat elke bestaande call werken met dezelfde betekenis, daarom zijn toevoegingen meestal veilig en verwijderingen, hernoemingen en aangescherpte regels meestal niet.</p> <p><strong>Telt het toevoegen van een verplicht veld?</strong> Ja. Elke bestaande call laat het weg, dus elke bestaande call faalt nu. Voeg het toe als optioneel met een verstandige standaardwaarde, of versioneer het endpoint.</p> <p><strong>Telt een bugfix?</strong> Kan zijn. Als aanroepers afhankelijk waren van het buggy gedrag, breekt het fixen ervan hen, wat de documentatie ook zei. Behandel elke fix die waarneembare output verandert als breaking, tenzij jullie kunnen aantonen dat niemand erop vertrouwde.</p> <p><strong>Geldt semantische versionering voor een web-API?</strong> De regel wel: breaking changes krijgen een nieuwe majorversie en de oude blijft werken voor een genoemde periode. Het nummer leeft vaak in de URL of een datum-header in plaats van in een pakketversie.</p> <p><strong>Hoeveel vooraankondiging is genoeg?</strong> Genoeg voor een aanroeper om de aankondiging te vinden en het werk te doen. Negentig dagen is een gangbare ondergrens voor publieke API's; langer voor alles wat wordt gebruikt in code die naar eindgebruikers wordt uitgebracht en niet op afstand kan worden bijgewerkt.</p> </article> <article> <h1>De feedback-loop sluiten vanuit de changelog</h1> <p>Sat, 29 Aug 2026 00:00:00 GMT</p> <p>Een klant-feedback-loop is gesloten wanneer de persoon die de feedback gaf te horen krijgt wat ermee is gebeurd. Niet wanneer die wordt geregistreerd. Niet wanneer die wordt geprioriteerd. Zelfs niet wanneer die wordt uitgebracht. Wanneer het haar wordt verteld. De meeste teams doen de eerste drie stappen goed en de laatste helemaal niet, en vragen zich dan af waarom mensen die feedback sturen ermee ophouden.</p> <p>Dit artikel gaat over die laatste stap, en over een concrete bewering: de changelog is de juiste plek om de loop vanaf te sluiten, omdat het het enige artefact is dat al bestaat op precies het moment waarop de loop gesloten kan worden.</p> <h2>Wat is een klant-feedback-loop?</h2> <p>Een klant-feedback-loop is het pad van een gebruiker die je iets vertelt tot die gebruiker verneemt wat je ermee hebt gedaan. Hij heeft vier stappen: de feedback verzamelen, beslissen wat ermee te doen, het resultaat uitbrengen, en de vrager inlichten. De loop is open tot de vierde stap plaatsvindt. Een team dat feedback verzamelt en fixes uitbrengt maar nooit iemand inlicht heeft een postvak, geen loop.</p> <table> <thead> <tr> <th>Stap</th> <th>Wat er gebeurt</th> <th>Waar het meestal breekt</th> </tr> </thead> <tbody><tr> <td>Verzamelen</td> <td>Feedback komt binnen: widget, support, sales, interviews</td> <td>Niets; elk team doet dit</td> </tr> <tr> <td>Beslissen</td> <td>Getrieerd, samengevoegd met duplicaten, geaccepteerd of afgewezen</td> <td>Afwijzingen worden nooit gecommuniceerd</td> </tr> <tr> <td>Uitbrengen</td> <td>Iemand bouwt het en het gaat live</td> <td>De link naar het verzoek raakt kwijt bij de merge</td> </tr> <tr> <td>Inlichten</td> <td>De aanvrager verneemt dat het is uitgebracht</td> <td>Overgeslagen, of alleen gedaan voor de luidruchtigste aanvrager</td> </tr> </tbody></table> <p>De vierde rij is waar dit artikel over gaat. Hij breekt om een structurele reden, niet een culturele: tegen de tijd dat een feature wordt uitgebracht, leeft het verzoek dat het veroorzaakte in een ander systeem dan het uitgebrachte ding, en het is niemands taak om ze te verbinden. De loop begint eerder, bij hoe het verzoek in de eerste plaats wordt gevraagd; <a href="https://changeloop.dev/blog/nl/how-to-ask-for-customer-feedback/">klantfeedback vragen</a> behandelt de formulering en het moment.</p> <h2>Waarom blijven feedback-loops open staan?</h2> <p>Feedback-loops blijven open staan omdat het verzoek en de uitgebrachte verandering op verschillende plekken leven en de link ertussen met de hand wordt gemaakt, als dat al gebeurt. Het verzoek staat in een feedbacktool, een supportpostvak of een spreadsheet. De verandering staat in een pull request. De aankondiging staat in een changelog of e-mail. Drie systemen, drie eigenaren, en de link van de derde terug naar de eerste is een persoon die zich maanden later herinnert wie het vroeg.</p> <p>Er is een tweede reden. De inlicht-stap wordt meestal ingekaderd als een marketingtaak ("de feature aankondigen") in plaats van een supporttaak ("de persoon antwoorden"). Aankondigingen gaan naar iedereen en bereiken niemand in het bijzonder. De persoon die in maart om de feature vroeg leest de aankondiging in juni, als ze die al leest, als nieuws, niet als antwoord. De loop sluit alleen als het bericht aan haar gericht is.</p> <h2>Waarom de loop sluiten vanuit de changelog?</h2> <p>Omdat de changelog-entry het enige artefact is dat exact op het juiste moment bestaat, exact de juiste woorden bevat, en geschreven wordt door exact de juiste persoon. Hij bestaat wanneer de verandering live is en niet eerder. Hij zegt wat er is veranderd in de taal van de lezer, wat het bericht is dat de aanvrager nodig heeft. En hij wordt geschreven door iemand die net de pull request heeft gelezen, wat het enige moment is waarop de link naar het oorspronkelijke verzoek nog zichtbaar is.</p> <p>Vergelijk de alternatieven. De loop sluiten vanuit de feedbacktool betekent dat de feedbacktool moet weten wanneer de feature is uitgebracht, wat betekent dat iemand met de hand een status bijwerkt. Hem sluiten vanuit de pull request betekent de klant inlichten bij de merge, voordat de verandering live is, een gebroken belofte met tijdstempel zodra de deploy vertraagt. Hem sluiten vanuit de marketingaankondiging betekent wachten op er een, en de meeste uitgebrachte veranderingen krijgen er nooit een.</p> <p>De changelog zit in het midden: na de merge, op het moment van uitbrengen, met de formulering klaar.</p> <h2>Hoe sluit de loop, stap voor stap</h2> <p>Dit is het mechanisme dat wij draaien. Het wordt hier beschreven als specificatie in plaats van producttour, omdat elke stap met de hand of met andere tools kan worden gedaan; wat ertoe doet is de volgorde.</p> <ol> <li><strong>Feedback wordt een issue in de repository die het gaat fixen.</strong> Een widget-inzending wordt geregistreerd als gelabelde GitHub-issue (<code>feature-request</code> of <code>bug</code>, een prioriteit, en <code>from-widget</code>), met het e-mailadres van de indiener buiten de body van de issue gehouden. De issue leeft naast de code, zodat stap drie hem kan vinden. Een met de hand aangemaakte issue, bijvoorbeeld vanuit een <a href="https://changeloop.dev/blog/nl/feature-request-template/">feature-request-template</a>, valt buiten dit pad: stap vijf plaatst er geen reactie op, dus sluit die loop zelf.</li> <li><strong>De fix verwijst naar de issue.</strong> De pull request zegt <code>Fixes #142</code>, GitHubs eigen sluitwoord. Niets nieuws te leren, en het is dezelfde zin die developers al schrijven.</li> <li><strong>De changelog-entry wordt opgesteld uit de gemergede pull request en draagt de link.</strong> Bij de merge wordt het concept aangemaakt en <code>#142</code> wordt uit de PR-body gelezen en aan het concept gehecht. De link wordt gemaakt terwijl hij nog goedkoop is, door een machine, uit data die er al is.</li> <li><strong>Een mens beoordeelt de entry.</strong> Formulering, doelgroep, of het überhaupt gepubliceerd moet worden. Een weggegooid concept sluit niets, wat correct is: een interne refactor die toevallig naar een issue verwees is geen nieuws.</li> <li><strong>Bij goedkeuring wordt de aanvrager ingelicht.</strong> Een reactie wordt geplaatst op de issue die van haar feedback werd gemaakt, "Shipped —" gevolgd door de titel van de entry en een link naar de gepubliceerde entry, en de widget toont de indiener dezelfde uitgebrachte entry. Eén keer, nooit twee keer, en pas nadat een mens de entry heeft gepubliceerd. Dezelfde entry gaat via <a href="https://changeloop.dev/docs">feed en widget</a> naar iedereen die niet vroeg.</li> </ol> <p>De volgorde in stap vijf is het hele ontwerp. De aanvrager inlichten bij de merge zou vroeger en makkelijker zijn, en zou fout zijn ongeveer even vaak als deploys vertragen. Een feature flag breekt zelfs deze volgorde, omdat goedgekeurd en gepubliceerd kan gebeuren terwijl de feature nog onzichtbaar is voor het account van de aanvrager; <a href="https://changeloop.dev/blog/nl/feature-flags-feature-requests/">feature flags en featureverzoeken</a> behandelt de extra check die deze stap nodig heeft zodra er een flag bij komt kijken.</p> <h2>Hoe ziet een gesloten loop eruit voor de klant?</h2> <p>Het ziet eruit als een antwoord. De klant stuurde een verzoek via een widget, en op een dag toont de widget het als uitgebracht, met een link naar een entry die het in haar taal beschrijft; op GitHub krijgt de issue hetzelfde nieuws als reactie. Ze abonneerde zich niet op een nieuwsbrief, controleerde geen roadmap, zocht niet in de changelog. Het werd haar verteld.</p> <p>Dat is de ervaring die het volgende stukje feedback veroorzaakt. Mensen sturen feedback naar producten die antwoorden. De pagina <a href="https://changeloop.dev/changelog-examples">changelog-voorbeelden</a> bevat entries van teams wier gebruikers zichtbaar blijven terugkomen met verzoeken, en de gemeenschappelijke draad is niet de tooling; het is dat de entries lezen als antwoorden.</p> <h2>Hoe meet je een feedback-loop?</h2> <p>Meet het aandeel uitgebrachte veranderingen dat minstens één aanvrager inlichtte, en de tijd van uitbrengen tot inlichten. Twee getallen, allebei makkelijk zodra de link bestaat en onmogelijk daarvoor.</p> <ul> <li><strong>Sluitingspercentage</strong>: van de deze maand gepubliceerde changelog-entries, hoeveel linkten naar minstens één verzoek, en daarvan, hoeveel lichtten de aanvrager in. Als het tweede getal veel lager is dan het eerste, falen de notificaties; als het eerste laag is, worden verzoeken niet vanuit pull requests gerefereerd, en de fix is een zin in de PR-template.</li> <li><strong>Tijd van uitbrengen tot inlichten</strong>: hoelang tussen de entry die live gaat en het inlichten van de aanvrager. Met het bovenstaande mechanisme zijn het seconden. Met de hand zijn het typisch weken, of nooit, en "nooit" is het getal dat ertoe doet.</li> </ul> <p>Meet de loop niet aan het volume verzamelde feedback. Verzamelen is de makkelijke stap, en een team dat het meet zal het optimaliseren, wat meer open loops oplevert.</p> <h2>Waar past de roadmap?</h2> <p>Een publieke roadmap is een manier om de loop vroeg te sluiten: het vertelt aanvragers dat hun verzoek is gehoord, voordat het wordt uitgebracht. Het is nuttig, en het vervangt de laatste stap niet. "Gepland" is een belofte over de toekomst; "Uitgebracht" is een feit over het heden. Draai de <a href="https://changeloop.dev/blog/nl/public-roadmap/">publieke roadmap</a> vanuit dezelfde issues, met een label per kolom, zodat hetzelfde verzoek van gepland naar uitgebracht beweegt zonder ergens opnieuw te worden ingevoerd. De stap naar uitgebracht is een labelwijziging (<code>roadmap:shipped</code>) die niemand voor je maakt wanneer de entry wordt goedgekeurd, dus doe het in dezelfde review.</p> <h2>FAQ</h2> <p><strong>Wat zijn de vier stappen van een klant-feedback-loop?</strong> Verzamelen, beslissen, uitbrengen, inlichten. De loop is open tot de vierde stap plaatsvindt. De meeste frameworks voegen analyse- en prioriteringsstappen in het midden toe; het zijn verfijningen van "beslissen", en geen enkele sluit iets.</p> <p><strong>Zou je klanten moeten inlichten wanneer een verzoek wordt afgewezen?</strong> Ja, en het is het meest verwaarloosde bericht in de loop. Een duidelijk "we gaan dit niet doen, en hier is waarom" beëindigt het wachten. Stilte laat de loop voor altijd open en de klant blijven controleren.</p> <p><strong>Hoe verschilt de loop sluiten van een feature aankondigen?</strong> Een aankondiging gaat naar iedereen. De loop sluiten is een antwoord aan de mensen die vroegen, op het kanaal waarlangs ze vroegen. Doe beide; het zijn verschillende berichten voor verschillende lezers.</p> <p><strong>Wat als de aanvrager niet op GitHub zit?</strong> De meesten zitten er niet, en dat is prima. De widget blijft hun de status tonen van wat ze stuurden, inclusief de uitgebrachte entry en de link ernaar, dus ze hebben niets nodig buiten de pagina waarvandaan ze schreven. De reactie op de issue is voor de mensen die de repository kunnen zien.</p> <p><strong>Werkt deze loop ook op GitLab of Bitbucket in plaats van GitHub?</strong> De widget en de changelog wel; de automatische reactie in stap vijf vandaag nog niet. Een team op GitLab of Bitbucket krijgt nog steeds elke inzending, registreert die nog steeds als issue, en toont de aanvrager nog steeds een status in de widget, maar die specifieke loop terugsluiten naar de issue zelf is voorlopig iets wat je met de hand doet totdat die integratie bestaat.</p> </article> <article> <h1>Feature-request-template die changelog wordt</h1> <p>Sat, 29 Aug 2026 00:00:00 GMT</p> <p>Een feature-request-template is een formulier met vier vragen: wat probeert de persoon te doen, wat houdt haar tegen, wat probeerde ze in plaats daarvan, en hoe wil ze ingelicht worden wanneer het klaar is. Al het andere dat meestal op zo'n formulier staat, prioriteitskeuzes, inschattingen van inspanning, business-value-scores, is voor het team dat het verzoek ontvangt, en wordt verkeerd ingevuld door de indiener.</p> <p>Nette verzoeken zijn de verkeerde test voor een template. De juiste: zes maanden later, wanneer de feature wordt uitgebracht, kan iemand het verzoek vinden, het begrijpen, en de schrijfster inlichten? De meeste templates zijn ontworpen voor intake. Deze is ontworpen voor de dag waarop de loop sluit.</p> <h2>Wat zou een feature-request-template moeten bevatten?</h2> <p>Hij zou het doel, de blokkade, de workaround, en een weg terug naar de aanvrager moeten bevatten. Vier velden, in die volgorde, elk beantwoordt een vraag die het team later zal stellen.</p> <table> <thead> <tr> <th>Veld</th> <th>De vraag die het later beantwoordt</th> <th>Waarom het op het formulier staat</th> </tr> </thead> <tbody><tr> <td>Wat probeer je te doen?</td> <td>Is de gebouwde feature degene die nodig was?</td> <td>Het doel overleeft elk concreet voorstel</td> </tr> <tr> <td>Wat houdt je vandaag tegen?</td> <td>Hoe ziet "klaar" eruit?</td> <td>Benoemt de kloof zonder de fix voor te schrijven</td> </tr> <tr> <td>Wat doe je in plaats daarvan?</td> <td>Hoe urgent is dit echt?</td> <td>Een pijnlijke workaround is een sterker signaal dan een prioriteitskeuze</td> </tr> <tr> <td>Hoe moeten we je inlichten?</td> <td>Wie krijgt het "uitgebracht"-bericht?</td> <td>Het veld dat de meeste templates weglaten</td> </tr> </tbody></table> <p>Wat er bewust ontbreekt: een voorgestelde oplossing als verplicht veld (welkom als commentaar, verkeerd als kader), een prioriteitskeuze (elke indiener kiest hoog), en elke inschatting van inspanning of waarde (taak van het team, na de triage). Een template die om een oplossing vraagt krijgt verzoeken voor knoppen; een template die om een doel vraagt krijgt verzoeken voor resultaten, en over resultaten schrijf je een changelog-entry.</p> <h2>De template</h2> <p>Dit is de GitHub-issue-template die wij gebruiken, als formulier. Plak hem in <code>.github/ISSUE_TEMPLATE/feature_request.yml</code> en hij wordt weergegeven als gestructureerd formulier op de nieuwe-issue-pagina. Verzoeken ingediend via dit formulier landen als issues met dezelfde velden als die ingediend vanuit een feedbackwidget, wat ertoe doet voor de volgende sectie.</p> <pre><code class="language-yaml">name: Feature request description: What you are trying to do, and what stops you. labels: ["feature-request"] body: - type: textarea id: goal attributes: label: What are you trying to do? description: >- The outcome, not the button. "Export a month of invoices as one PDF" beats "add a PDF export". validations: required: true - type: textarea id: blocker attributes: label: What stops you today? description: >- Where the product runs out. An error, a missing option, a limit. validations: required: true - type: textarea id: workaround attributes: label: What do you do instead? description: >- The spreadsheet, the script, the manual step. "Nothing, I gave up" is a valid answer. - type: input id: contact attributes: label: How should we tell you when it ships? description: >- An email address, or leave blank to be notified only on this issue. </code></pre> <p>Twee details doen het werk. <code>labels: ["feature-request"]</code> betekent dat het verzoek bij aanmaak wordt geclassificeerd in plaats van te wachten tot iemand het trieert. En het laatste veld bestaat omdat "we laten het je weten" een belofte is, en een belofte heeft een adres nodig.</p> <h2>Welke labels zou een feature-verzoek moeten dragen?</h2> <p>Een feature-verzoek zou een label moeten dragen voor wat het is, een voor hoe urgent het is, en een voor waar het vandaan komt. Drie labels, drie assen, en elk wordt door een andere lezer gelezen.</p> <table> <thead> <tr> <th>Label</th> <th>Waarden</th> <th>Wie het leest</th> </tr> </thead> <tbody><tr> <td>Soort</td> <td><code>feature-request</code>, <code>bug</code></td> <td>Wie beslist in welke wachtrij het komt</td> </tr> <tr> <td>Prioriteit</td> <td><code>priority:low</code>, <code>priority:medium</code>, <code>priority:high</code></td> <td>Wie de volgende cyclus plant</td> </tr> <tr> <td>Bron</td> <td><code>from-widget</code>, <code>from-form</code>, <code>from-support</code></td> <td>Wie meet waar verzoeken vandaan komen</td> </tr> </tbody></table> <p>De widget past de eerste twee assen en <code>from-widget</code> toe wanneer die een inzending als issue registreert; <code>from-form</code> en <code>from-support</code> zijn suggesties voor verzoeken die via andere wegen binnenkomen. De labels van de widget zijn een soort (<code>bug</code> of <code>feature-request</code>, beslist door een classifier alleen op basis van het bericht), een prioriteit (een kalm, specifiek crashrapport is hoog; een duplicaat van iets al gevraagd is laag; alles wat zelfs maar suggereert een securityprobleem te zijn is <code>bug</code> en hoog, ongeacht de formulering), en <code>from-widget</code>. Dezelfde drie assen werken voor verzoeken die met de hand binnenkomen via de bovenstaande template, en dat is het punt: een verzoek is een verzoek, waar het ook binnenkwam.</p> <p>Nog een conventie: de widget verwijdert het e-mailadres van de indiener uit de issue-body voordat hij hem registreert, omdat de issue in een repository leeft die publiek kan zijn, en vervangt het door een indieningsreferentie. Het adres blijft buiten de issue; de indiener volgt de uitkomst in de widget zelf. Doe hetzelfde met het contactveld als jullie tracker zichtbaar is voor mensen buiten het team.</p> <h2>Hoe wordt een feature-verzoek een changelog-entry?</h2> <p>Een feature-verzoek wordt een changelog-entry wanneer een pull request de issue sluit en de entry die uit die pull request is opgesteld terug linkt. Het mechanisme zijn GitHubs eigen sluitwoorden: een PR waarvan de beschrijving <code>Fixes #142</code> zegt sluit issue 142 bij de merge. Als jullie changelog-entries worden opgesteld uit gemergede pull requests, kan het concept het issue-nummer meedragen, en weet de entry wie vroeg.</p> <p>Dat is de reden waarom de template om het doel vraagt in plaats van de oplossing. Wanneer de entry wordt geschreven, is het doel de zin die de schrijver nodig heeft: "Je kunt nu een maand facturen exporteren als één PDF" is een changelog-entry. "PDF-export toegevoegd" is een commitbericht. De <a href="https://changeloop.dev/changelog-tools">changelog-tools</a> die opstellen uit pull requests kunnen de verzameling en de link doen; de formulering heeft nog steeds een mens nodig, en de mens heeft het doel nodig.</p> <h2>Wat gebeurt er wanneer het wordt uitgebracht?</h2> <p>De aanvrager wordt ingelicht, met een link naar de entry. In onze opzet gebeurt dat automatisch voor verzoeken die via de widget binnenkwamen: een reactie die "Shipped — <titel van de entry>" zegt met een link naar de gepubliceerde entry, geplaatst op de issue zodra een mens de entry heeft goedgekeurd, terwijl de widget de indiener dezelfde entry toont. Een issue die met de hand vanuit deze template is aangemaakt, krijgt geen automatische reactie; sluit die loop zelf, volgens dezelfde regel. De reactie wordt bewust geplaatst bij goedkeuring in plaats van bij de merge: een reactie die zegt dat iets live is voordat het dat is, is een gebroken belofte met tijdstempel. Elk verzoek wordt hoogstens één keer genotificeerd; een tweede goedkeuring van dezelfde entry produceert geen tweede reactie.</p> <p>Als jullie dit met de hand doen, geldt dezelfde regel. Sluit de loop niet vanuit de pull request. Sluit hem vanuit de gepubliceerde entry, en sluit hem één keer. <a href="https://changeloop.dev/docs">Feed en widget</a> dragen dezelfde entry naar iedereen die niet vroeg, wat de meesten zijn; de reactie is voor wie vroeg.</p> <h2>Waarom de meeste feature-request-templates falen</h2> <p>Ze zijn ontworpen om triage makkelijker te maken en dat lukt, ten koste van het enige moment dat ertoe doet voor de aanvrager. Een template met twaalf velden krijgt minder verzoeken, en degene die hij krijgt komen van mensen met het geduld om twaalf velden in te vullen, wat niet dezelfde populatie is als die de feature nodig heeft. Een template met vier velden, waarvan één "hoe bereiken we je", krijgt meer verzoeken en kan ze allemaal eer aandoen.</p> <h2>FAQ</h2> <p><strong>Zou een feature-request-template om prioriteit moeten vragen?</strong> Nee. Vraag in plaats daarvan naar de workaround. "Ik exporteer naar een spreadsheet en tik het elke vrijdag opnieuw in" zegt meer over prioriteit dan een keuzemenu dat de indiener op hoog zette.</p> <p><strong>Zouden aanvragers een oplossing moeten voorstellen?</strong> Dat mag, in de vrije tekst. Maak het niet het kader. Als oplossingen geformuleerde verzoeken zijn lastiger samen te voegen en lastiger om te veranderen in een changelog-entry.</p> <p><strong>Zouden feature-verzoeken op een publieke roadmap moeten verschijnen?</strong> Zodra ze gepland zijn, ja: een label op dezelfde issue zet hem in de geplande kolom, en de aanvrager kan zien hoe het beweegt. Het artikel <a href="https://changeloop.dev/blog/nl/public-roadmap/">publieke roadmap</a> is het mechanisme.</p> <p><strong>Hoe ga ik om met duplicaten?</strong> Link het nieuwe verzoek aan de bestaande issue en label hem lage prioriteit; sluit hem niet. Elk duplicaat is nog een persoon om in te lichten wanneer het wordt uitgebracht. Met de automatische reactie van Changeloop wordt die persoon alleen ingelicht als de pull request ook haar issue noemt (<code>Fixes #142, fixes #187</code>).</p> <p><strong>Waar zou de template moeten leven?</strong> In de repository die de pull request zal ontvangen, zodat het sluitwoord werkt. Een verzoek in een aparte tracker moet met de hand worden gelinkt bij de merge, en dat is de stap die wordt overgeslagen.</p> </article> <article> <h1>Publieke roadmap uit je issue tracker, drie kolommen</h1> <p>Sat, 29 Aug 2026 00:00:00 GMT</p> <p>Een publieke roadmap is een lijst van wat jullie van plan zijn te bouwen, gepubliceerd waar klanten hem kunnen zien. Het woord dat het werk doet is <em>van plan</em>: een roadmap is een verzameling beloftes over de toekomst, en elk item erop is er een dat jullie zullen houden of waarvan zichtbaar zal worden dat jullie dat niet doen. Dat is de reden om er een te publiceren, en het is ook de reden waarom de meeste publieke roadmaps binnen een kwartaal verouderen. De versie die overleeft is klein, afgeleid uit data die jullie al onderhouden, en aan het andere eind verbonden met de changelog, zodat een belofte een feit wordt zonder dat iemand hem opnieuw invoert.</p> <h2>Waarvoor dient een publieke roadmap?</h2> <p>Een publieke roadmap vertelt een klant met een verzoek dat het verzoek is gehoord, voordat het wordt uitgebracht. Het is de vroege helft van het sluiten van de loop: "gepland" beantwoordt de vraag "heeft iemand dit gelezen", en "in ontwikkeling" beantwoordt "gebeurt dit echt". Geen van beide vervangt de laatste stap, de aanvrager inlichten wanneer het wordt uitgebracht, maar beide verminderen het aantal mensen dat ondertussen vraagt.</p> <p>Het doet ook iets voor het team: het dwingt een publieke verplichting af, wat de goedkoopste bekende remedie is tegen een backlog dat stilletjes vierhonderd items vasthoudt die niemand zal bouwen.</p> <table> <thead> <tr> <th>Kolom</th> <th>De belofte die hij maakt</th> <th>Wat een item erin verplaatst</th> </tr> </thead> <tbody><tr> <td>Gepland</td> <td>We zijn van plan dit te bouwen</td> <td>Een beslissing, vastgelegd als label op de issue</td> </tr> <tr> <td>In ontwikkeling</td> <td>Iemand werkt er nu aan</td> <td>Een <code>roadmap:building</code>-label op de issue</td> </tr> <tr> <td>Uitgebracht</td> <td>Het is live</td> <td>Een <code>roadmap:shipped</code>-label, of de issue sluiten terwijl die het label draagt</td> </tr> </tbody></table> <p>Drie kolommen, in vaste volgorde, zijn genoeg. Een vierde kolom ("in overweging", "onder beoordeling", "backlog") is waar goede bedoelingen een museum worden, en het is de eerste die klanten leren te negeren.</p> <h2>Zou jullie roadmap publiek moeten zijn?</h2> <p>Maak hem publiek als jullie hem klein en eerlijk kunnen houden; houd hem privé als het alternatief een lange lijst met misschiens is. De kosten van een publieke roadmap hebben niets te maken met het publiceren ervan: elk item erop is nu een vraag die iemand zal stellen, in support, in verkoopgesprekken en in verlengingsgesprekken. Tien items die jullie zullen bouwen zijn een activum. Zestig items die jullie misschien zullen bouwen zijn zestig toekomstige gesprekken over waarom niet.</p> <p>Twee eerlijke redenen om niet te publiceren: jullie plannen veranderen sneller dan een kwartaal, of jullie concurrentie leest jullie roadmap zorgvuldiger dan jullie klanten. Beide zijn echt, en beide worden beantwoord door minder te publiceren in plaats van niets: alleen "in ontwikkeling", met "gepland" intern gehouden, vertelt een aanvrager toch dat haar issue beweegt.</p> <h2>Hoe bouw je een publieke roadmap uit GitHub-issues?</h2> <p>Zet een label per kolom op de issues die jullie al bijhouden, en render de gelabelde issues als de roadmap. Niets wordt opnieuw ingevoerd, de roadmap kan niet van het werk afdrijven, en dezelfde issue die begon als klantverzoek beweegt door de kolommen zonder van identiteit te veranderen.</p> <p>Het mechanisme, zoals wij het draaien:</p> <ol> <li><strong>Eén label per kolom, met vast prefix</strong>: <code>roadmap:planned</code>, <code>roadmap:building</code>, <code>roadmap:shipped</code>. Elke issue in een verbonden repository die er een draagt verschijnt in die kolom. Een issue zonder een van deze staat niet op de roadmap, wat de meeste issues zijn, wat correct is.</li> <li><strong>De kolommen zijn een geordende array, altijd in dezelfde volgorde.</strong> Gepland, in ontwikkeling, uitgebracht. Geen map geïndexeerd op naam, zodat een lezer (of een widget) nooit naar de volgorde hoeft te raden.</li> <li><strong>Als een issue twee labels draagt, wint de verst gevorderde.</strong> Iemand zal <code>roadmap:shipped</code> toevoegen voordat <code>roadmap:planned</code> wordt verwijderd; een toestandsmachine gestuurd door "welke webhook laatst binnenkwam" zou het item in verschillende kolommen zetten afhankelijk van de leveringsvolgorde. Beslissen op basis van alleen de labelverzameling maakt het antwoord hetzelfde ongeacht hoe events binnenkomen.</li> <li><strong>Uitgebracht is een labelstatus zoals de andere.</strong> De kaart verplaatst wanneer de issue <code>roadmap:shipped</code> krijgt, of wordt gesloten terwijl die het label draagt. De kaart zelf linkt niet naar de changelog-entry; de entry, opgesteld uit de pull request die de issue sloot, is waar de details staan.</li> <li><strong>Serveer hem als data.</strong> De roadmap is een JSON-document met die drie kolommen, gepubliceerd naast de changelog-feed met dezelfde cache-headers, zodat een docsite, een widget of een statuspagina hem kunnen renderen zonder tweede integratie. De <a href="https://changeloop.dev/docs">feed-documentatie</a> heeft de exacte vorm.</li> </ol> <p>Een label is weinig gevraagd van een maintainer, en het is de hele integratie. Geen bord om gesynchroniseerd te houden, geen apart tool om in te loggen, en het verzoek dat de klant registreerde is het item op de roadmap; wanneer het wordt uitgebracht, is het hetzelfde item.</p> <h2>Wat zou een publieke roadmap niet moeten bevatten?</h2> <p>Hij zou geen datums, inschattingen, of iets moeten bevatten waar jullie je over negen maanden voor zouden schamen als ernaar gevraagd wordt. Datums zijn de klassieke fout: een kwartaal op een roadmap wordt een verplichting in een verkoopdeck wordt een ticket genaamd "jullie zeiden Q3". Kolommen zeggen genoeg. "In ontwikkeling" betekent al "snel genoeg dat iemand eraan zit".</p> <p>Hij zou ook de interne backlog niet moeten bevatten. Een roadmap met driehonderd items is een zoekprobleem, geen belofte, en de klant die haar verzoek op positie 212 vindt heeft iets geleerd dat jullie haar niet wilden vertellen.</p> <h2>Hoe verbindt de roadmap met de changelog?</h2> <p>De roadmap en de changelog beschrijven dezelfde issues van twee kanten, één voor de toekomst en één voor het verleden. Niemand verplaatst een kaart op een apart bord. Een maintainer verandert het label op de issue waar hij al in werkte, de entry wordt opgesteld uit de pull request, en wanneer een mens die entry goedkeurt wordt een aanvrager van wie de widget-feedback die issue werd daar ingelicht. De kaart naar uitgebracht verplaatsen blijft een eigen stap, het <code>roadmap:shipped</code>-label, dus maak het onderdeel van dezelfde review; het goedkeuren van de entry doet het niet voor jullie.</p> <p>Dit is dezelfde loop die het <a href="https://changeloop.dev/blog/nl/customer-feedback-loop/">artikel over de feedback-loop</a> beschrijft vanuit de changelog-kant; de roadmap is wat de klant er middenin van ziet. Het overzicht <a href="https://changeloop.dev/changelog-tools">changelog-tools</a> dekt welke producten een roadmap-weergave bieden en welke het als apart bord behandelen, wat het verschil is dat beslist of hij accuraat blijft.</p> <h2>Hoe ziet een goede publieke roadmap eruit?</h2> <p>Hij ziet er kort uit, en elk item erop is een issue die iedereen kan openen. De test is of een klant van een item naar de discussie erachter kan gaan, en van een uitgebracht item naar de entry die beschrijft wat er daadwerkelijk is veranderd. Een roadmap die een lijst van featurenamen is zonder ingang is een brochure.</p> <p>Een uitgewerkt voorbeeld, als de JSON die een widget zou ophalen:</p> <pre><code class="language-json">{ "columns": [ { "column": "planned", "hasMore": false, "items": [ { "id": "6b0c1f...", "column": "planned", "publicTitle": "Saved views on the inbox", "publicDescription": "Keep a filter you use often and come back to it.", "publishedAt": "2026-09-16T10:04:11.000Z" } ]}, { "column": "building", "hasMore": false, "items": [ { "id": "71a4e2...", "column": "building", "publicTitle": "Roadmap column in the widget", "publicDescription": "See what is coming without leaving the page.", "publishedAt": "2026-09-12T08:20:02.000Z" } ]}, { "column": "shipped", "hasMore": false, "items": [ { "id": "5c9d70...", "column": "shipped", "publicTitle": "Feedback filed as labelled issues", "publicDescription": "Widget submissions arrive as issues your triage already handles.", "publishedAt": "2026-09-02T15:41:37.000Z" } ]} ], "enabled": true, "language": "en" } </code></pre> <p>Drie items over drie kolommen zijn een prima goede publieke roadmap. Hij zegt wat er komt, wat er gebeurt, en wat er is gebeurd, en elke regel is controleerbaar. Vijf andere opzetten, van Now/Next/Later tot uitkomstgericht, staan met voorbeelditems in <a href="https://changeloop.dev/blog/nl/product-roadmap-examples/">product roadmap voorbeelden</a>.</p> <h2>FAQ</h2> <p><strong>Hoeveel items zou een publieke roadmap moeten hebben?</strong> Zo weinig als jullie kunnen verdedigen. Onder de tien in totaal is normaal voor een klein product; meer dan dertig in "gepland" is een backlog verkleed als roadmap.</p> <p><strong>Zou een publieke roadmap datums moeten hebben?</strong> Nee. Kolommen communiceren volgorde zonder een deadline te creëren. Als een klant een datum nodig heeft, is dat een gesprek, geen roadmap-item.</p> <p><strong>Zouden klanten moeten stemmen op roadmap-items?</strong> Stemmen meten wie kwam opdagen, niet wat ertoe doet. Een reactie op de issue die de workaround uitlegt die ze vandaag gebruiken is meer waard dan vijftig stemmen, en kost de stemmer iets, wat het punt is.</p> <p><strong>Wat gebeurt er met een geannuleerd roadmap-item?</strong> Verwijder het label en zeg waarom op de issue. Een publiek "we gaan dit niet doen" maakt deel uit van de loop, en het is het bericht dat de meeste teams nooit versturen.</p> </article> <article> <h1>Changelog-automatisering, en haar grenzen</h1> <p>Fri, 28 Aug 2026 00:00:00 GMT</p> <p>Changelog-automatisering werkt wanneer die verzameling, classificatie en publicatie automatiseert, en stopt bij selectie en formulering. Automatiseer alles en je levert een geformatteerde git log; automatiseer niets en de changelog wordt in vlagen geschreven, uit het geheugen, vlak voor releases. De nuttige vraag is welke delen te automatiseren, niet hoeveel.</p> <p>Changelog-automatiseringsprojecten falen in één van twee richtingen, en beide zijn voorspelbaar vanaf de eerste ontwerpvergadering. Automatiseer te weinig en de changelog is een document dat iemand geacht wordt bij te werken, wat betekent dat het in vlagen wordt bijgewerkt, door wie de korte lucifer trok. Automatiseer te veel en het wordt een geformatteerde git log: compleet, accuraat, en door niemand gelezen.</p> <h2>Welke delen van een changelog zouden geautomatiseerd moeten worden?</h2> <p>Drie van de vier stappen. Verzameling en publicatie volledig; classificatie als eerste doorgang met menselijke override; selectie en formulering nooit.</p> <table> <thead> <tr> <th>Stap</th> <th>Automatiseren?</th> <th>Waarom</th> </tr> </thead> <tbody><tr> <td>Verzameling: veranderingen uit commits, PR's, tickets in een lijst</td> <td>Volledig</td> <td>Vervelend, wordt onder deadline overgeslagen, machines doen het perfect</td> </tr> <tr> <td>Classificatie: Added, Fixed, Changed, Deprecated, Removed, Security</td> <td>Eerste doorgang, menselijke override</td> <td>Ongeveer 80% juist alleen uit metadata; de foute 20% zijn de entries die ertoe doen</td> </tr> <tr> <td>Selectie en formulering: wat je de lezer vertelt, en hoe</td> <td>Nooit</td> <td>Dit is de hele waarde van het artefact</td> </tr> <tr> <td>Publicatie: pagina, feed, e-mail, widget, Slack</td> <td>Volledig, vanuit één bron</td> <td>Waar het meeste handmatige werk daadwerkelijk naartoe gaat</td> </tr> </tbody></table> <p><strong>Verzameling.</strong> Veranderingen uit de plek halen waar ze gebeuren (commits, PR's, tickets) en in een lijst zetten. Automatiseer dit volledig. Mensen zijn er slecht in, het is vervelend, en het is de stap die onder deadline wordt overgeslagen. <a href="https://changeloop.dev/blog/nl/conventional-commits-changelog/">Conventional commits</a> of PR-labels zijn het gebruikelijke ruwe materiaal.</p> <p><strong>Classificatie.</strong> Beslissen of iets Added, Fixed, Changed, Deprecated, Removed of Security is. Automatiseer de eerste doorgang uit het commit-type of PR-label, en laat een mens overriden. De nauwkeurigheid hier ligt rond de tachtig procent puur uit metadata, en de foute twintig procent concentreert zich precies op de entries die ertoe doen, omdat dubbelzinnigheid correleert met belang.</p> <p><strong>Selectie en formulering.</strong> Beslissen wat een lezer verteld moet worden en hoe het te zeggen. <strong>Automatiseer dit niet.</strong> Het is de hele waarde van het artefact. Al het andere is logistiek.</p> <p><strong>Publicatie.</strong> De afgeronde entries naar een pagina, een feed, een e-mail, een in-app-widget, een Slack-kanaal brengen. Automatiseer volledig, en vanuit één bron. Hier gaat het meeste handmatige werk daadwerkelijk naartoe, en bijna niemand telt het. Het is ook de stap die de persoon die om de verandering vroeg kan vertellen dat die is uitgebracht, wat het hele onderwerp is van <a href="https://changeloop.dev/blog/nl/customer-feedback-loop/">de feedback-loop sluiten vanuit de changelog</a>. De e-mailhelft van die stap heeft zijn eigen vorm, in <a href="https://changeloop.dev/blog/nl/product-update-email/">de product-update e-mailtemplate</a>.</p> <p>Dat laatste punt is het waard om bij stil te staan. Teams neigen ertoe de changelog te zien als een schrijfprobleem, en besteden dan de meeste tijd aan distributie: entries kopiëren naar een e-mailtool, herformatteren voor in-app, plakken in Slack, een docspagina bijwerken. Het schrijven kost een uur. Het kopiëren kost een uur per release, voor altijd, en dat is het deel dat een machine zou moeten hebben.</p> <h2>Wat gebeurt er als de grens verschuift?</h2> <p><strong>Verschuif hem omhoog en je krijgt een git-dump.</strong> Volledige automatisering uit commits levert <code>bump deps</code>, <code>fix flaky test</code>, <code>wip</code> en <code>address review comments</code> voor klanten. Elk team dat dit heeft gedaan heeft daarna een filter toegevoegd, en het filter is een selectiestap die onder een andere naam opnieuw wordt geïntroduceerd, met slechtere ergonomie.</p> <p><strong>Verschuif hem omlaag en je krijgt vlagen.</strong> Volledig handmatige verzameling betekent dat entries op releasemoment uit het geheugen worden geschreven. Dat is de modus waar <a href="https://changeloop.dev/blog/nl/keep-a-changelog-implemented/">Keep a Changelog</a> meteen al voor waarschuwt, en het verslechtert stilletjes: de changelog lijkt onderhouden tot precies de week dat niemand tijd had.</p> <h2>Hoe ziet een changelog-automatiseringspipeline eruit?</h2> <p>Vier stappen, met precies één menselijke poort, geplaatst waar een concept publiek wordt.</p> <ol> <li>Leid bij het mergen een conceptentry af uit de PR: type uit label of commit-prefix, titel als eerste concept, link terug naar de PR, auteur vastgelegd. Zet het in een unreleased-bak.</li> <li>Iedereen kan elk concept op elk moment bewerken, en bewerken is goedkoop. De meeste krijgen één regel herschreven.</li> <li>Een release snijden vereist dat elke entry in de bak of bewerkt of expliciet als intern gemarkeerd is. Deze poort is het hele ontwerp. Zonder haar worden concepten ongewijzigd uitgebracht in de drukke week.</li> <li>Publiceren is een fan-out vanuit de uitgebrachte set: de publieke pagina, de feed, de e-mail, de widget, de Slack-post. Eén bron, meerdere weergaven, geen kopiëren.</li> </ol> <p>Stap 3 is de enige plek waar een mens nodig is, en het duurt ongeveer tien minuten per release zodra de concepten fatsoenlijk zijn. Waar een klantverzoek bij betrokken is, draagt het concept ook de issue die het sluit, wat is wat stap 4 in staat stelt de aanvrager te informeren; de <a href="https://changeloop.dev/blog/nl/feature-request-template/">feature-request-template</a> is zo ontworpen dat die link overleeft. Waar deze stap in de bredere releaseflow zit, is het onderwerp van het <a href="https://changeloop.dev/blog/nl/release-management-process/">releasemanagementproces</a>.</p> <h2>Wat vereist automatisering van jullie data?</h2> <p>Niets van het bovenstaande werkt als de changelog een Markdown-bestand is, want een bestand kan niet naar vijf oppervlakken worden weergegeven zonder opnieuw te worden geparset, en proza parsen is hoe je eindigt met een widget die de helft van een kop toont.</p> <p>Entries moeten gestructureerd zijn: een type, een datum, een versie of release-identifier, een doelgroep, een body en een link. Dan zijn het bestand, de pagina, de feed en de e-mail allemaal weergaven. Dat structurele punt is het enige wat de moeite waard is om goed te doen voordat je een tool kiest, omdat het is wat je niet goedkoop kunt naboren. Niets daarvan werkt zolang er niet echt een item wordt gemaakt voor elke wijziging die het nodig heeft; <a href="https://changeloop.dev/blog/nl/changelog-ci-enforcement/">een changelog-item afdwingen in CI</a> behandelt hoe je de pipeline een merge zonder item laat weigeren, in plaats van die stap aan het geheugen over te laten.</p> <p>Wij bouwen <a href="https://changeloop.dev/">changeloop</a>, waar de changelog eerst een feed is en dan pas een pagina, dus lees dit als een belang in plaats van een onpartijdige aanbeveling; de <a href="https://changeloop.dev/pricing">prijzen</a> zijn één gratis repository zonder kaart, genoeg om de vorm te zien. <a href="https://changeloop.dev/changelog-tools">Changelog-tools</a> is ons overzicht van wat er verder is, inclusief de producten waarmee we concurreren, en de <a href="https://changeloop.dev/changelog-generator">changelog-generator</a> doet de verzamelings- en classificatiestappen in de browser als je de afleiding wilt zien voordat je je aan een pipeline verbindt.</p> <h2>De test</h2> <p>Tel de minuten tussen een gemergede verandering en die verandering zichtbaar voor een klant die jullie repo niet leest. Als de meeste van die minuten iemand is die tekst tussen tools kopieert, is de automatisering die jullie nodig hebben in de publicatie, niet in het schrijven.</p> <h2>FAQ</h2> <p><strong>Kan AI de changelog schrijven?</strong> Die kan er een opstellen. Een model dat de gemergede pull request krijgt levert meestal een bruikbaar eerste concept van titel en body op, wat de verzamelings- en classificatiestappen beter gedaan is. De selectie, of een lezer überhaupt iets verteld moet worden, en de uiteindelijke formulering hebben nog steeds de persoon nodig die de doelgroep kent, en een pipeline die concepten publiceert zonder die poort heeft de verkeerde stap geautomatiseerd.</p> <p><strong>Wat is het verschil tussen een changelog-generator en changelog-automatisering?</strong> Een generator zet commits eenmalig, op verzoek, om in een geformatteerde lijst. Automatisering draait bij elke merge, houdt een unreleased-bak bij, laat de release afhangen van menselijke review, en publiceert naar elk oppervlak vanuit één bron. De generator is de eerste, met de hand uitgevoerde stap van de pipeline.</p> <p><strong>Zou de changelog geautomatiseerd moeten worden uit commits of uit pull requests?</strong> Uit pull requests, waar de eenheid van verandering de PR is: de titel en beschrijving worden eenmalig geschreven, voor de hele verandering, en de PR linkt de issue die het sluit. Commit-gebaseerde afleiding werkt wanneer de commit de eenheid is en een conventie volgt.</p> <p><strong>Hoe voorkom je dat automatisering interne veranderingen publiceert?</strong> Classificeer <code>chore</code>, <code>ci</code>, <code>test</code>, <code>refactor</code> en dependency-updates standaard als intern, en maak promotie naar publiek een bewuste handeling. De omgekeerde standaard, publiek tenzij iemand het verbergt, is hoe <code>bump deps</code> klanten bereikt.</p> </article> <article> <h1>Changelog vs release notes: wat is het verschil?</h1> <p>Fri, 28 Aug 2026 00:00:00 GMT</p> <p>Een changelog is een doorlopend, cumulatief register van alles wat is veranderd, geschreven voor iemand die iets opzoekt. Release notes zijn een gecureerd bericht over één release, geschreven voor iemand die beslist of het hem interesseert. Het verschil zit in het publiek, niet in de opmaak, en de meeste teams hebben beide nodig: één als naslagwerk, één als aankondiging, afgeleid uit dezelfde entries.</p> <p>De meeste teams eindigen per ongeluk met het één en op verzoek met het ander. Je begint met een changelog omdat een developer een register wil van wat is uitgebracht. Maanden later vraagt iemand van support waarom klanten niet wisten van een functie die al sinds april live is, en nu heb je release notes nodig.</p> <h2>Changelog vs release notes, naast elkaar</h2> <table> <thead> <tr> <th></th> <th>Changelog</th> <th>Release notes</th> </tr> </thead> <tbody><tr> <td>Lezer</td> <td>Iemand die iets opzoekt</td> <td>Iemand die beslist of het hem interesseert</td> </tr> <tr> <td>Bereik</td> <td>Alles wat is veranderd</td> <td>Wat de moeite waard is om over deze release te zeggen</td> </tr> <tr> <td>Cadans</td> <td>Doorlopend, per merge of per release</td> <td>Per release, en alleen die het aankondigen waard zijn</td> </tr> <tr> <td>Toon</td> <td>Beknopt, feitelijk, vaak gebiedend</td> <td>Uitleggend, soms overtuigend</td> </tr> <tr> <td>Levensduur</td> <td>Permanent, ook jaren later gelezen</td> <td>Gelezen in de eerste week, dan gearchiveerd</td> </tr> <tr> <td>Leeft in</td> <td>Het repo, een docsite, een <code>/changelog</code>-pagina</td> <td>E-mail, in-app, een blogpost, een releasepagina</td> </tr> <tr> <td>Faalt door</td> <td>Onvolledig zijn</td> <td>Saai zijn, of te laat komen</td> </tr> </tbody></table> <h2>Wat is een changelog?</h2> <p>Een changelog is een chronologisch, bijna compleet register van wat is veranderd, meest recent eerst, met elke entry getypeerd (added, changed, deprecated, removed, fixed, security) en gedateerd. De lezer heeft al besloten dat het hem interesseert. Hij zoekt iets op: wanneer een gedrag veranderde, of een bug is opgelost, welke versie een flag introduceerde. Volledigheid is de hele waarde, en daarom besteedt de conventie <a href="https://changeloop.dev/blog/nl/keep-a-changelog-implemented/">Keep a Changelog</a> het grootste deel van zijn ene pagina aan structuur en bijna niets aan proza.</p> <h2>Wat zijn release notes?</h2> <p>Release notes zijn een selectief, in proza geschreven bericht over één release. De lezer heeft nog niets besloten. Hij beslist of deze release hem interesseert, en of hij er iets aan moet doen. Selectie is de hele waarde: een release note die alles opsomt is een changelog met alinea's, en faalt de lezer op dezelfde manier waarop een changelog die dingen overslaat zijn lezer faalt. <a href="https://changeloop.dev/blog/nl/how-to-write-release-notes/">Hoe schrijf je release notes</a> gaat over de selectie en de formulering.</p> <h2>Heb je zowel een changelog als release notes nodig?</h2> <p>Je hebt beide nodig zodra je twee doelgroepen verschillende dingen willen; tot die tijd is één artefact dat beide banen doet correct. Kleine teams publiceren één <code>/changelog</code>-pagina met een korte alinea bovenaan elke entry, en een tijdlang dient dat een developer die een fix opzoekt en een klant die scant naar nieuws even goed. Te vroeg splitsen geeft je twee dingen om te onderhouden en een daarvan zal wegrotten.</p> <p>De splitsing wordt de moeite waard wanneer dit begint te gebeuren:</p> <ul> <li>Jullie changelog-entries zijn uitgegroeid tot uitleggende alinea's die developers overslaan.</li> <li>Of het tegenovergestelde: jullie release-aankondigingen zijn dependency-updates gaan opsommen.</li> <li>Support kopieert entries naar e-mails en herschrijft ze onderweg.</li> <li>Iemand vraagt om "alleen de breaking changes" en jullie kunnen daar niet op filteren.</li> </ul> <p>Die laatste is het echte teken. Als niemand kan antwoorden "wat is er veranderd dat mij treft" zonder alles te lezen, hebben jullie één artefact dat twee banen slecht doet.</p> <h2>Eén bron, twee weergaven</h2> <p>De fout is ze als twee documenten te behandelen. Het zijn twee weergaven op dezelfde set veranderingen.</p> <p>Schrijf de changelog gaandeweg, één entry per betekenisvolle verandering, elk gelabeld met wat het is: fixed, added, changed, removed, deprecated, security. Houd de entries kort genoeg dat er één schrijven geen beslissing is. Dan, op releasemoment, zijn release notes een selectie en een herschrijving: neem de entries die een mens interesseren, groepeer ze op wat ze iemand laten doen, en zet de reden bovenaan.</p> <p>Dit heeft een praktisch gevolg. Als de changelog de bron is, moet die gestructureerde data zijn, geen handmatig onderhouden pagina. Een entry heeft een type, een datum, een versie, en een manier nodig om te zeggen voor wie het is. Zodra dat er is, zijn de publieke pagina, de in-app-widget en de RSS- of JSON-feed drie weergaven van één ding, en herschrijft niemand iets onderweg naar een klant. Een release-notes-e-mail kan dezelfde entry citeren, vanuit welke tool je e-mail ook verstuurt. <a href="https://changeloop.dev/blog/nl/changelog-automation/">Changelog-automatisering</a> gaat over welke van die stappen een machine zou moeten bezitten. Dat is het hele argument om een changelog als feed te behandelen in plaats van als pagina. Het is ook, met volledige transparantie, wat wij bouwen, dus lees dit als een belang in plaats van een onpartijdig onderzoek.</p> <h2>Als je maar tijd hebt voor één</h2> <p>Schrijf de changelog. Het is goedkoper per entry, nuttig op de dag dat je het schrijft, en release notes kunnen er later uit worden afgeleid. Het omgekeerde geldt niet: je kunt geen jaar aan veranderingen reconstrueren uit twaalf aankondigingsmails, en mensen zullen het je vragen.</p> <p>Houd het in een vast formaat zodat de afleiding mogelijk blijft. Onze pagina <a href="https://changeloop.dev/changelog-examples">changelog-voorbeelden</a> verzamelt entries van teams die dit goed doen, en de <a href="https://changeloop.dev/release-notes-template">release notes template</a> is de vorm die we gebruiken om een set entries om te zetten in iets dat de moeite waard is om te versturen.</p> <h2>Een noot over naamgeving</h2> <p>Niets hiervan is gestandaardiseerd, en je zult "release notes" tegenkomen voor een doorlopende lijst en "changelog" voor een kwartaalaankondiging. Discussiëren over de woorden is het niet waard. Beslis welke van de twee taken elk van jullie artefacten doet, noem het zoals jullie team het al noemt, en zorg dat geen van beide stilletjes beide doet.</p> <p>Op welk oppervlak het resultaat terechtkomt is een aparte beslissing, behandeld in <a href="https://changeloop.dev/blog/nl/changelog-page/">een changelogpagina bouwen</a>.</p> <h2>FAQ</h2> <p><strong>Is een changelog hetzelfde als release notes?</strong> Nee. Een changelog is het complete register, gelezen door wie iets opzoekt; release notes zijn de geselecteerde aankondiging, gelezen door wie beslist of het hem interesseert. Dezelfde verandering verschijnt in beide, anders geformuleerd voor elke lezer.</p> <p><strong>Kunnen release notes uit een changelog worden gegenereerd?</strong> Ja, en dat is de juiste richting. Selecteer de entries die een mens zouden interesseren, groepeer ze op resultaat, herschrijf de kop. Het omgekeerde, een changelog reconstrueren uit aankondigingen, verliest alles wat de aankondigingen hebben weggelaten.</p> <p><strong>Waar zou een changelog moeten leven?</strong> Ergens permanents en koppelbaars dat de lezer kan bereiken zonder repository: een <code>/changelog</code>-pagina, een docsite, of een feed die op meerdere plekken wordt weergegeven. Een <code>CHANGELOG.md</code> alleen bereikt bijdragers, geen klanten.</p> <p><strong>Zou een changelog interne veranderingen moeten bevatten?</strong> Ja, onderaan, elk één regel. De changelog is het complete register. Release notes kunnen ze ook bevatten, in een korte laatste sectie, zolang de veranderingen die een lezer zal merken eerst komen.</p> </article> <article> <h1>Van conventional commits naar een changelog</h1> <p>Fri, 28 Aug 2026 00:00:00 GMT</p> <p>Conventional commits geven een changelog drie dingen gratis: het type van elke verandering, het deel van het systeem dat het raakte, en of het iets breekt. Meer geven ze niet. Formulering, groepering en selectie, wat de changelog is, blijven volledig open, en een pipeline die anders doet alsof levert een geformatteerde git log.</p> <pre><code>feat(exports): add CSV column selection fix(auth): reject expired refresh tokens chore(deps): bump node-pg to 8.11 </code></pre> <p>Drie commits in het formaat <a href="https://www.conventionalcommits.org/">Conventional Commits</a>. Hieruit kan een machine je vertellen dat de een een feature is, de een een fix, de een huishouding, en welk deel van het systeem elk raakte. Dat is echt nuttig, en het is de hele belofte van de conventie: een commit-geschiedenis die door iets anders dan een persoon kan worden gelezen. De fout is denken dat dat je een changelog oplevert. Het levert je de grondstof.</p> <h2>Wat specificeert de conventie?</h2> <p>Een type, een optioneel scope, en een beschrijving: <code>type(scope): description</code>. Types zijn conventioneel <code>feat</code>, <code>fix</code>, <code>chore</code>, <code>docs</code>, <code>refactor</code>, <code>test</code>, <code>perf</code>, <code>build</code>, <code>ci</code>. Twee dingen markeren een breaking change: een <code>!</code> voor de dubbele punt, of een <code>BREAKING CHANGE:</code>-footer. Tooling stuurt op <code>feat</code> en <code>fix</code> voor minor- en patch-versiesprongen, en op de breaking-marker voor een major.</p> <table> <thead> <tr> <th>De commit geeft je</th> <th>De changelog heeft nodig</th> <th>Wie de kloof opvult</th> </tr> </thead> <tbody><tr> <td><code>feat</code> / <code>fix</code> / <code>chore</code></td> <td>Added / Fixed / intern</td> <td>Een mapping, automatisch</td> </tr> <tr> <td><code>(scope)</code></td> <td>Een groepering die de lezer herkent</td> <td>Een persoon, eenmaal per scope</td> </tr> <tr> <td><code>!</code> of <code>BREAKING CHANGE:</code></td> <td>Wie breekt, tegen wanneer, en wat te doen</td> <td>Een persoon, elke keer</td> </tr> <tr> <td>De beschrijving, geschreven voor een reviewer</td> <td>Het resultaat, geschreven voor een klant</td> <td>Een persoon, elke entry</td> </tr> <tr> <td>Eén commit</td> <td>Eén verandering, die meerdere commits kan zijn</td> <td>Squash-regels, of een persoon</td> </tr> </tbody></table> <p>De marker vertelt het aan de tooling; het vertelt het niet aan de aanroeper, wat het onderwerp is van <a href="https://changeloop.dev/blog/nl/api-deprecation/">hoe deprecieer je een API</a> en <a href="https://changeloop.dev/blog/nl/breaking-changes/">wat is een breaking change</a>. Het is een kleine spec en het is de moeite waard om te volgen, zelfs als je er nooit iets uit genereert, omdat het één beslissing per commit afdwingt: is dit een verandering die gebruikers zien, of niet.</p> <h2>Waar stoppen conventional commits?</h2> <p>Ze stoppen bij de zin. Alles wat de conventie vastlegt is metadata over een verandering; de verandering zelf wordt nog steeds beschreven in het vocabulaire van een reviewer.</p> <p><strong>Commitberichten zijn geschreven voor reviewers.</strong> <code>fix(auth): reject expired refresh tokens</code> is correct en vertelt een klant niets. De lezer van een changelog wil "je wordt uitgelogd wanneer een sessie echt is verlopen, in plaats van intermitterende 401's te zien".</p> <p><strong>Scopes zijn intern.</strong> <code>exports</code>, <code>auth</code>, <code>ingest</code> zijn modulenamen. Ze zijn stabiel, wat ze goed maakt om te groeperen, en betekenisloos voor iedereen buiten de codebase.</p> <p><strong>Eén verandering is vaak meerdere commits.</strong> Een feature die over elf commits is gemerged produceert elf entries, tien daarvan ruis, en die weg-squashen om dat te verbergen verliest de reviewgeschiedenis.</p> <p><strong><code>chore</code> is een prullenbak, geen categorie.</strong> Dependency-updates, CI-wijzigingen en hernoemingen belanden allemaal daar, en sommige tellen voor gebruikers terwijl de meeste niet.</p> <p>Dus: de conventie geeft je type, scope en breaking-status gratis, en laat formulering, groepering en selectie volledig open. Die drie zijn de changelog. <a href="https://changeloop.dev/blog/nl/changelog-entry-ownership/">Wie is eigenlijk eigenaar van een changelog-item</a> behandelt wie zich met die formulering, groepering en selectie zou moeten bezighouden, aangezien de conventie zelf daar geen mening over heeft.</p> <h2>Hoe genereer je een changelog uit conventional commits?</h2> <p>In twee lagen, en de tweede moet verplicht zijn.</p> <p><strong>Laag één, automatisch.</strong> Leid bij het mergen een conceptentry af uit de commit: type gemapt naar een changelog-type (<code>feat</code> naar Added, <code>fix</code> naar Fixed, een breaking-marker naar Changed plus een vlag), scope bewaard als metadata in plaats van als tekst, link naar de PR. Zet het in de Unreleased-sectie die <a href="https://changeloop.dev/blog/nl/keep-a-changelog-implemented/">Keep a Changelog</a> vraagt.</p> <p><strong>Laag twee, menselijk, en vereist.</strong> Voordat een release uitgaat, krijgt elke conceptentry ofwel een herschrijving van één regel in het vocabulaire van de gebruiker, ofwel wordt hij intern gemarkeerd en uit de publieke weergave gehaald. Dit is de stap die mensen proberen over te slaan, en overslaan is wat changelogs oplevert die als een diff lezen.</p> <p>Het belangrijke ontwerpdetail is dat laag twee niet optioneel is in de pipeline. Als een release kan worden gesneden met ongewijzigde concepten, zal dat gebeuren, in de week dat iedereen het druk heeft. Welke stappen bij de machine horen en welke bij de persoon is het hele onderwerp van <a href="https://changeloop.dev/blog/nl/changelog-automation/">changelog-automatisering</a>.</p> <p>De release snijden is ook het moment waarop een git-tag, een release en deze changelog-regel of samenkomen of uit sync beginnen te raken; <a href="https://changeloop.dev/blog/nl/git-tags-releases-changelog/">git-tags, releases en je changelog</a> behandelt hoe je de drie synchroon houdt.</p> <h2>Drie valkuilen</h2> <p><strong>Squash-merges eten de footers op.</strong> Als jullie platform squasht met de PR-titel als bericht, verdwijnt de <code>BREAKING CHANGE:</code>-footer van een commit binnen die branch, en jullie tooling stopt stilletjes met het zien van de breaking change. Controleer wat jullie squash-template werkelijk bewaart.</p> <p><strong>Revert-commits produceren spookentries.</strong> Een <code>fix</code> die de volgende dag wordt gerevert genereert een entry voor iets dat nooit is uitgebracht, tenzij de afleiding reverts verrekent. De meeste tools doen dat niet.</p> <p><strong>Versiesprong en changelog raken uit de pas.</strong> Als de versie wordt berekend uit commits en de changelog daarna met de hand wordt geschreven, drijven ze binnen ongeveer twee releases uiteen. Bereken beide in dezelfde stap of accepteer dat een van de twee fout is.</p> <h2>Als je het mechanische deel wilt zonder pipeline</h2> <p>Onze <a href="https://changeloop.dev/changelog-generator">changelog-generator</a> doet de afleidingsstap in de browser: plak commits, krijg gegroepeerde, getypeerde entries. Het is bewust deterministisch en volledig clientside, dus de commits die je plakt verlaten nooit je machine, wat telt wanneer de berichten uit een privérepository komen. Het doet de verzamelingshelft eerlijk en waagt geen poging tot laag twee, omdat laag twee een oordeel is en een tool die dat veinst precies de changelog oplevert waartegen dit artikel argumenteert.</p> <p>Voor de pipelineversie dekt <a href="https://changeloop.dev/changelog-tools">changelog-tools</a> wat er bestaat.</p> <h2>De samenvatting</h2> <p>Conventional commits beantwoorden "wat voor soort verandering is dit" betrouwbaar en goedkoop. Ze beantwoorden niet "wat moeten we mensen vertellen", en geen hoeveelheid tooling boven op het commitbericht zal dat doen, omdat de informatie nooit in het commitbericht zat. Begroot de herschrijving.</p> <h2>FAQ</h2> <p><strong>Genereren conventional commits automatisch een changelog?</strong> Ze genereren automatisch een concept: getypeerde, gescopte, gelinkte entries. De formulering voor een klant, de groepering en de beslissing wat weg te laten hebben nog steeds een persoon nodig, en een pipeline die die stap overslaat publiceert commitberichten.</p> <p><strong>Welke conventional-commit-types verschijnen in een changelog?</strong> <code>feat</code> en <code>fix</code> altijd, als Added en Fixed. <code>perf</code> meestal, als Changed. <code>chore</code>, <code>docs</code>, <code>refactor</code>, <code>test</code>, <code>build</code> en <code>ci</code> zijn standaard intern en verschijnen alleen als een persoon er een promoot.</p> <p><strong>Hoe markeren conventional commits een breaking change?</strong> Een <code>!</code> na het type of scope (<code>feat(api)!: ...</code>), of een <code>BREAKING CHANGE:</code>-footer in de body van de commit. Beide gaan verloren als een squash-merge alleen de PR-titel behoudt.</p> <p><strong>Heb je conventional commits nodig om een changelog te automatiseren?</strong> Nee. PR-labels, PR-templates en issue-links dragen dezelfde metadata voor teams die via pull request mergen. Conventional commits zijn de goedkoopste optie wanneer de eenheid van verandering de commit is.</p> </article> <article> <h1>Hoe schrijf je release notes die mensen echt lezen</h1> <p>Fri, 28 Aug 2026 00:00:00 GMT</p> <p>Om release notes te schrijven die mensen lezen, beantwoord één vraag per entry: wat kan de lezer nu doen dat eerst niet kon, en wat moet die daaraan doen. Zet alles met een deadline vooraan, noem wie het treft, zeg "geen actie nodig" als dat waar is, en sla releases over die niks te melden hebben. Al het andere op deze pagina is die regel toegepast.</p> <blockquote> <p>Bugfixes en prestatieverbeteringen.</p> </blockquote> <p>Elk product heeft dit ooit gepubliceerd. De oorzaak is zelden luiheid: dit krijg je als release notes van binnenuit worden geschreven, door iemand die twee weken in de diff heeft gezeten en niet meer kan zien welke delen een buitenstaander zouden interesseren. Een betere schrijfstijl lost dat niet op; de vraag beantwoorden wel.</p> <h2>Wat zouden release notes moeten bevatten?</h2> <p>Release notes zouden voor elke vermeldenswaardige verandering moeten bevatten: wat de lezer nu kan doen, wie het betreft, wat die moet doen (inclusief "niets"), en wanneer iets met een deadline ingaat. Ze zouden geen interne ticketnummers, componentnamen die alleen het team gebruikt, of een versienummer als enige kop moeten bevatten.</p> <table> <thead> <tr> <th>Wel opnemen</th> <th>Weglaten</th> </tr> </thead> <tbody><tr> <td>Het resultaat, in de taal van de lezer</td> <td>De implementatie, in de taal van het team</td> </tr> <tr> <td>Wie het treft, per plan, rol of API-versie</td> <td>"Sommige gebruikers"</td> </tr> <tr> <td>De vereiste actie, of "geen actie nodig"</td> <td>Stilte, die de lezer met het ergste scenario invult</td> </tr> <tr> <td>Een datum voor alles met een deadline</td> <td>Een versienummer in plaats van een datum</td> </tr> <tr> <td>Een link naar de doc die het uitlegt</td> <td>Een link naar de pull request</td> </tr> <tr> <td>Bugs die zijn gemeld, en de limiet die omhoog ging</td> <td>Interne ticket-id's</td> </tr> <tr> <td>De saaie sectie, elk één regel, onderaan</td> <td>De saaie sectie vermengd met het nieuws</td> </tr> </tbody></table> <p>Het onderscheid tussen een release note en een <a href="https://changeloop.dev/blog/nl/changelog-vs-release-notes/">changelog-entry</a> maakt deze lijst mogelijk: de changelog houdt alles bij, dus de notes mogen dingen weglaten. Geannoteerde voorbeelden van elk entrytype staan in <a href="https://changeloop.dev/blog/nl/release-notes-examples/">release notes voorbeelden</a>.</p> <h2>De vraag die elke entry beantwoordt</h2> <p><strong>Wat kan de lezer nu doen dat eerst niet kon, en wat moet die daaraan doen?</strong></p> <p>Als een entry dat niet kan beantwoorden, hoort die in de changelog thuis en niet in de release notes. Beide helften tellen. De eerste helft is de waarde. De tweede helft is die de teams vergeten, en het is degene die supporttickets oplevert als hij ontbreekt.</p> <p>Twee voorbeelden van de tweede helft die echt werk verzet:</p> <ul> <li>"Bestaande webhooks blijven werken tot 1 november. Daarna worden ongesigneerde payloads geweigerd."</li> <li>"Geen actie nodig. Bestaande exports worden automatisch opnieuw gecodeerd de volgende keer dat je ze opent."</li> </ul> <p>De tweede zegt expliciet "geen actie nodig". Die zin is elke keer weer het schrijven waard, omdat een lezer die hem niet vindt het ergste aanneemt.</p> <h2>Hoe zou je release notes moeten ordenen?</h2> <p>Orden ze naar gevolg voor de lezer, nooit naar het deel van het systeem dat veranderde. Groeperen op API, dashboard, mobiel en infrastructuur is jullie organogram, niet het probleem van de lezer.</p> <ol> <li><strong>Breaking changes en alles met een deadline.</strong> Altijd eerst, ook als het klein is. Als een lezer na één regel stopt met lezen, is dit de regel die die gelezen moet hebben. Als de deadline een sunset is, zou de entry moeten klinken als een <a href="https://changeloop.dev/blog/nl/api-deprecation/">deprecatiebericht</a>.</li> <li><strong>Wat nieuw is en waar ze op zaten te wachten.</strong> Eén per alinea, met het resultaat in de eerste zin.</li> <li><strong>Wat beter werd.</strong> Bugs die zijn gemeld, limieten die omhoog gingen, dingen die traag waren.</li> <li><strong>Al het andere, als lijst.</strong> Dependency-updates, interne refactors, kleine copy. Elk één regel. Niemand leest deze sectie, en toch moet hij er zijn, want wie hem zoekt heeft hem echt nodig.</li> </ol> <h2>De herschrijving</h2> <p>Voor:</p> <blockquote> <p><strong>v4.2.0</strong> Probleem opgelost waarbij het endpoint <code>POST /exports</code> af en toe 500 teruggaf onder belasting. Export-worker gerefactored. <code>node-pg</code> bijgewerkt naar 8.11. Foutafhandeling in de CSV-serializer verbeterd.</p> </blockquote> <p>Na:</p> <blockquote> <p><strong>Exports falen niet meer bij grote accounts.</strong> Accounts met ruim 50.000 rijen konden een 500 krijgen bij het starten van een export, vaker rond het einde van de maand. Dat is opgelost, en exports van elke omvang proberen zichzelf nu opnieuw in plaats van te falen. Geen actie nodig, en elke export die vorige week faalde kan gewoon opnieuw worden uitgevoerd.</p> <p>Ook in 4.2.0: <code>node-pg</code> 8.11, duidelijkere fouten in de CSV-serializer.</p> </blockquote> <p>Dezelfde release. De tweede noemt het getroffen account, het moment waarop het het ergst was, wat er veranderde, en wat te doen. De dependency-update is niet verdwenen, hij is alleen gestopt de kop te zijn. Het artikel <a href="https://changeloop.dev/blog/nl/release-notes-best-practices/">beste practices voor release notes</a> heeft de rest van de regels die deze herschrijving volgt, elk met wat het kost om ze over te slaan.</p> <h2>Dingen die het waard zijn om te schrappen</h2> <ul> <li><strong>"We zijn verheugd om aan te kondigen."</strong> De lezer is nog niet verheugd. Verdien dat in de volgende zin.</li> <li><strong>Interne ticketnummers.</strong> <code>PROJ-4471</code> betekent niets buiten jullie tracker. Als de entry een verwijzing nodig heeft, link naar de docpagina.</li> <li><strong>Componentnamen die alleen jullie team gebruikt.</strong> Als je de "ingest-pipeline" hebt hernoemd, zeg dan "imports".</li> <li><strong>Een versienummer als enige kop.</strong> <code>v4.2.0</code> is een archiveringslabel, geen samenvatting.</li> <li><strong>Screenshots van een instellingenpagina die niemand ooit bezocht.</strong> Toon wat er veranderd is, in gebruik.</li> </ul> <h2>Hoe vaak zou je release notes moeten publiceren?</h2> <p>Publiceer wanneer er iets is gebeurd, niet volgens een schema. Notes die bij elke release komen leren iedereen ze te negeren. Notes die komen wanneer er iets is gebeurd worden geopend. Het is prima, en meestal juist, om een release zonder enige note uit te brengen en de entries te laten meelopen in de volgende set die een kop heeft die de moeite van het lezen waard is.</p> <p>De changelog blijft alles vastleggen. Dat is de taakverdeling: de changelog is compleet, de notes zijn selectief. Als je de changelog gaandeweg gestructureerd houdt, wordt het schrijven van de notes selectie en herschrijven in plaats van archeologie.</p> <p>De <a href="https://changeloop.dev/release-notes-template">release notes template</a> is de vorm die we gebruiken voor de selectiestap, en <a href="https://changeloop.dev/changelog-examples">changelog-voorbeelden</a> verzamelt entries van teams wier changelog goed genoeg is om notes uit af te leiden.</p> <p>Dit alles veronderstelt een pagina die je volledig controleert, zonder lengtelimiet en met links die werken. <a href="https://changeloop.dev/blog/nl/mobile-app-release-notes/">Release notes voor mobiele apps</a> behandelt wat er verandert als het oppervlak een App Store- of Play Store-vermelding is. <a href="https://changeloop.dev/blog/nl/emergency-release-notes/">Noodrelease notes</a> behandelt de andere uitzondering: wat er verandert als er helemaal geen tijd meer is om het normale schrijfproces te volgen.</p> <h2>Eén test voor je publiceert</h2> <p>Lees de notes als iemand die twee weken op vakantie is geweest en 40 seconden heeft. Als die persoon in die tijd niet kan zien of er iets van hem gevraagd wordt, zijn de notes niet af, hoe accuraat ze ook zijn.</p> <h2>FAQ</h2> <p><strong>Hoe lang zouden release notes moeten zijn?</strong> Zo lang als de gevolgtrekkende veranderingen vereisen, en geen regel langer. Een release met één breaking change en twee verbeteringen is drie alinea's. Een rustige release opvullen om substantieel te lijken is hoe lezers leren de notes over te slaan.</p> <p><strong>Wie zou release notes moeten schrijven?</strong> De persoon die de verandering begrijpt, geredigeerd door iemand die dat niet doet. De engineer weet wat er veranderd is; de redacteur weet wat een buitenstaander verkeerd zal lezen. De entry schrijven op het moment van de merge, terwijl de engineer het zich nog herinnert, is de praktijk die dit goedkoop maakt.</p> <p><strong>Zouden release notes bugfixes moeten bevatten?</strong> Ja, die iemand heeft gemeld of tegenkwam. Vermeld het symptoom dat de lezer zag, niet de oorzaak. "Exports van meer dan 50.000 rijen faalden" is een fix die een lezer herkent; "race condition in de export-worker opgelost" is een commitbericht.</p> <p><strong>Wat is het verschil tussen release notes en een changelog?</strong> De changelog is het complete, doorlopende register; de release notes zijn het gecureerde bericht over één release, geschreven voor mensen die nog niet hebben besloten of het ze interesseert. Het langere antwoord staat in <a href="https://changeloop.dev/blog/nl/changelog-vs-release-notes/">changelog vs release notes</a>.</p> </article> <article> <h1>Keep a Changelog, écht geïmplementeerd</h1> <p>Fri, 28 Aug 2026 00:00:00 GMT</p> <p>Keep a Changelog is een conventie van één pagina voor een <code>CHANGELOG.md</code>: meest recente versie eerst, één sectie per versie met een nummer en een ISO-datum, entries gegroepeerd onder zes types (Added, Changed, Deprecated, Removed, Fixed, Security), en een Unreleased-sectie bovenaan voor entries tussen releases. De meeste teams die er naar verwijzen implementeren ongeveer tweederde ervan, en het derde dat ze laten vallen is het derde dat hun gebruikers beschermt.</p> <p>Olivier Lacan publiceerde <a href="https://keepachangelog.com/">Keep a Changelog</a> in 2014 met een zin die beter is verouderd dan het meeste softwareproza: <em>don't let your friends dump git logs into changelogs</em>. Tien jaar later is het het dichtste wat dit hoekje van software heeft bij een standaard. Het is de moeite waard om de bron te lezen in plaats van een samenvatting; dit gaat over de delen die worden weggelaten.</p> <h2>Wat vraagt Keep a Changelog?</h2> <p>Een <code>CHANGELOG.md</code> in de root van het repo, meest recent eerst, met één sectie per versie. Elke versie draagt een nummer en een ISO-datum, en groepeert zijn entries onder zes types:</p> <table> <thead> <tr> <th>Type</th> <th>Voor</th> <th>Wat het kost om weg te laten</th> </tr> </thead> <tbody><tr> <td>Added</td> <td>Nieuwe functies</td> <td>Niets; niemand laat deze weg</td> </tr> <tr> <td>Changed</td> <td>Veranderingen in bestaand gedrag</td> <td>Lezers ontdekken een gedragsverandering door een fout</td> </tr> <tr> <td>Deprecated</td> <td>Functies die worden verwijderd</td> <td>Een verwijdering wordt een incident in plaats van een gepland moment</td> </tr> <tr> <td>Removed</td> <td>Functies verwijderd in deze release</td> <td>Niemand onderscheidt een verwijdering van een bug</td> </tr> <tr> <td>Fixed</td> <td>Bugfixes</td> <td>Niets; niemand laat deze ook weg</td> </tr> <tr> <td>Security</td> <td>Kwetsbaarheden</td> <td>De ene lezer die ernaar zocht vindt hem niet</td> </tr> </tbody></table> <p>Plus een <code>Unreleased</code>-sectie bovenaan, zodat er een plek is voor een entry zodra die wordt gemerged, en zodat iedereen kan zien wat eraan komt.</p> <p>Dat is bijna alles. De rest is de redenering: entries zijn voor mensen, één entry per verandering, en het bestand is een document in plaats van een log.</p> <h2>Welke delen van Keep a Changelog worden weggelaten?</h2> <p>De Unreleased-sectie, dan vier van de zes types, Security daaronder, in die volgorde.</p> <p><strong><code>Unreleased</code> verdwijnt als eerste.</strong> Het is de sectie zonder deadline, dus het is degene waarvan het onderhoud als eerste stopt, en zodra hij weg is worden entries op releasemoment geschreven uit de commit-geschiedenis. Dat is precies de git-log-dump waar de spec meteen al voor waarschuwt, geleidelijk bereikt. <a href="https://changeloop.dev/blog/nl/changelog-automation/">Changelog-automatisering</a> gaat vooral over deze sectie levend houden zonder dat iemand het hoeft te onthouden.</p> <p><strong>De zes types klappen in tot twee.</strong> De meeste echte changelogs eindigen met Added en Fixed, omdat Changed en Deprecated een oordeel vereisen over waar iemand op vertrouwde. Dat oordeel is het waardevolle deel. Deprecated is in het bijzonder het enige type dat een belofte over de toekomst is, en het weglaten ervan is hoe een verwijdering een incident wordt; de mechanica om die belofte te houden staat in <a href="https://changeloop.dev/blog/nl/api-deprecation/">hoe deprecieer je een API</a>.</p> <p><strong>Security stopt apart te zijn.</strong> Een securityfix onder Fixed is onzichtbaar voor de ene lezer die ernaar zocht. Houd het gescheiden, ook als de fix triviaal is, en vooral wanneer je liever geen aandacht erop wilt vestigen.</p> <h2>Wat beantwoordt de spec niet?</h2> <p>Het is een bestandsformaat. Hij zegt niets over de vragen die je meteen tegenkomt na het adopteren ervan:</p> <ul> <li><strong>Hoe komt iemand erachter?</strong> Een bestand in een repo bereikt bijdragers. Het bereikt geen klant die nooit GitHub heeft geopend.</li> <li><strong>En producten zonder versies?</strong> Een continu gedeployde dienst heeft geen v4.2.0 om op te groeperen. De meeste teams vervangen dat door datums, wat werkt, en de spec zegent noch verbiedt dat.</li> <li><strong>Wie schrijft de entry?</strong> De spec gaat ervan uit dat een mens dat doet. Hij zegt niet wanneer.</li> <li><strong>En meerdere doelgroepen?</strong> Eén bestand bedient developers. Het bedient een niet-technische beheerder niet dezelfde inhoud, en dat handmatig voor haar herformatteren is waar de duplicatie begint. <a href="https://changeloop.dev/blog/nl/changelog-vs-release-notes/">Changelog vs release notes</a> is de splitsing die de spec je zelf laat maken.</li> </ul> <p><a href="https://common-changelog.org/">Common Changelog</a>, een strengere fork van het idee, verstrengt een deel hiervan: het verbiedt bepaalde entryformuleringen, vereist een link naar de verandering, en heeft een uitgesproken mening over wie de lezer is. De moeite waard om te lezen als de losse onderdelen van Keep a Changelog zijn waar jullie team steeds over blijft ruziën.</p> <h2>Kun je Keep a Changelog automatiseren zonder git logs te dumpen?</h2> <p>Ja: leid het concept af uit gestructureerde commits, zet het in Unreleased met zijn type voor-ingevuld, en vereis dat een mens de formulering bewerkt voordat een release wordt gesneden. De waarschuwing van de spec gaat over de uitvoer, niet over de tooling. Een concept afleiden uit commits is prima. Dat concept ongewijzigd publiceren is waar hij zich tegen verzet.</p> <p>De machine handelt verzameling en opmaak af, waar hij goed in is. De mens handelt selectie en formulering af, waar hij dat niet in is. <a href="https://changeloop.dev/blog/nl/conventional-commits-changelog/">Conventional commits</a> behandelt de tweelaagse opdeling waar dit op leunt, en welke committypes op welke van de zes categorieën hierboven mappen. Ons overzicht <a href="https://changeloop.dev/changelog-tools">changelog-tools</a> dekt wat er bestaat voor de verzamelingshelft.</p> <h2>Waar stopt Keep a Changelog voldoende te zijn?</h2> <p>Het stopt bij distributie. Keep a Changelog is een goed antwoord op "hoe zou dit bestand eruit moeten zien". Het is geen antwoord op "hoe komen onze gebruikers erachter wat er veranderd is", omdat een Markdown-bestand in een repo een distributiestrategie is die alleen werkt als jullie gebruikers bijdragers zijn.</p> <p>Dat is het obstakel dat de meeste teams als tweede tegenkomen: het bestand is prima, en niemand buiten het team leest het. Het oplossen betekent dat de entries data moeten worden die elders kunnen worden weergegeven, wat een ander probleem is dan een bestand opmaken, en de reden waarom <a href="https://changeloop.dev/changelog-examples">changelog-voorbeelden</a> publieke changelog-pagina's verzamelt in plaats van repobestanden. Hoe je die entries omzet in iets waar mensen op terugkomen, behandelt <a href="https://changeloop.dev/blog/nl/changelog-page/">een changelogpagina bouwen</a>.</p> <p>Adopteer de spec toch. Het kost een middag, het maakt het tweede probleem behapbaar, en het is nog steeds de beste pagina die ooit over dit onderwerp is geschreven.</p> <h2>FAQ</h2> <p><strong>Is Keep a Changelog een standaard?</strong> Het is een breed geadopteerde conventie, geen specificatie van een normalisatie-instituut. Tooling (release-scripts, linters, parsers) veronderstelt zijn vorm vaak genoeg dat het volgen ervan compatibiliteit koopt.</p> <p><strong>Wat komt er in de Unreleased-sectie?</strong> Elke entry voor een verandering die is gemerged maar nog niet is uitgebracht in een genummerde release. Wanneer een release wordt gesneden, wordt de sectie hernoemd naar de versie en datum, en komt er een nieuwe lege Unreleased-sectie erboven.</p> <p><strong>Zou een changelog semantische versionering moeten gebruiken?</strong> Keep a Changelog raadt het aan en vereist het niet. Bibliotheken en API's hebben er baat bij; een continu gedeployde dienst vervangt meestal door datums, wat het formaat toelaat.</p> <p><strong>Zouden securityfixes in de changelog moeten staan voordat ze publiek zijn?</strong> Voeg de entry toe wanneer de fix wordt uitgebracht, met genoeg detail zodat een operator kan handelen en niet meer. De entry uitstellen tot een gecoördineerde openbaarmakingsdatum is normaal; hem weglaten niet.</p> </article> <article> <h1>Beste practices voor release notes die het waard zijn</h1> <p>Fri, 28 Aug 2026 00:00:00 GMT</p> <p>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.</p> <p>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.</p> <table> <thead> <tr> <th>Practice</th> <th>Wat het kost om over te slaan</th> </tr> </thead> <tbody><tr> <td>De entry schrijven bij de merge, niet bij de release</td> <td>Later gereconstrueerde entries zeggen "diverse verbeteringen"</td> </tr> <tr> <td>Noem wie het treft</td> <td>Elke lezer besluit dat het niet op hem van toepassing is</td> </tr> <tr> <td>Vermeld de vereiste actie, inclusief "geen"</td> <td>Veertig identieke supporttickets, en lezers die het ergste aannemen</td> </tr> <tr> <td>Dateer breaking changes, versie ze niet</td> <td>De deadline wordt ontdekt nadat hij verstreken is</td> </tr> <tr> <td>Eén permanente, koppelbare entry per verandering</td> <td>Niemand kan antwoorden "wanneer is dit veranderd"</td> </tr> <tr> <td>Groepeer op resultaat, niet op systeem</td> <td>Lezers hebben jullie architectuur nodig om hun sectie te vinden</td> </tr> <tr> <td>Houd de saaie sectie</td> <td>Security, compliance en wie een versiemismatch debugt verliezen hun bron</td> </tr> </tbody></table> <h2>Wat zijn de beste practices voor release notes?</h2> <p><strong>Schrijf de entry als je mergt, niet als je uitbrengt.</strong> 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.</p> <p><strong>Zeg wie het treft, bij naam.</strong> "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.</p> <p><strong>Vermeld de vereiste actie, ook als het er geen is.</strong> 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.</p> <p><strong>Geef breaking changes een datum, geen releasenummer.</strong> "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 <a href="https://changeloop.dev/blog/nl/breaking-changes/">wat is een breaking change</a>.</p> <p><strong>Houd één permanente, koppelbare entry per verandering.</strong> 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 <a href="https://changeloop.dev/blog/nl/product-update-email/">de product-update e-mailtemplate</a>; hij wijst naar de entry in plaats van hem te vervangen.</p> <p><strong>Groepeer op resultaat, niet op systeem.</strong> 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 <a href="https://changeloop.dev/blog/nl/how-to-write-release-notes/">hoe schrijf je release notes</a>.</p> <p><strong>Houd de saaie sectie.</strong> 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; <a href="https://changeloop.dev/blog/nl/bug-fix-release-notes/">bugfix release notes</a> laat zien hoe je ze schrijft zodat een lezer weet of hij moet handelen.</p> <h2>Wat zijn de beste practices voor een changelog, en hoe verschillen die?</h2> <p>Een changelog is een naslagwerk, dus zijn practices gaan over volledigheid en structuur in plaats van overtuiging. De vier die ertoe doen:</p> <ul> <li><strong>Een vast entrytype per regel.</strong> 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 <a href="https://changeloop.dev/blog/nl/keep-a-changelog-implemented/">Keep a Changelog</a> is de gebruikelijke bron.</li> <li><strong>Een unreleased-sectie.</strong> Waar entries leven tussen merge en release. Het ontbreken ervan is de reden waarom teams entries laat schrijven.</li> <li><strong>ISO-datums.</strong> <code>2026-08-28</code>, niet <code>28/08/26</code>, wat twee verschillende dagen betekent afhankelijk van de lezer.</li> <li><strong>Eén entry per verandering, niet per commit.</strong> Drie commits die één bug oplossen zijn één entry.</li> </ul> <p>De twee artefacten worden grondig vergeleken in <a href="https://changeloop.dev/blog/nl/changelog-vs-release-notes/">changelog vs release notes</a>; de korte versie is dat de practices van de changelog volledigheid beschermen en die van de release notes aandacht beschermen. <a href="https://changeloop.dev/blog/nl/private-release-notes-enterprise/">Private release notes voor enterprise-klanten</a> 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.</p> <h2>Drie die pure cargocultus zijn</h2> <p><strong>Emoji als entrytypes.</strong> 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.</p> <p><strong>Semantische versienummers als koppen voor een gehost product.</strong> 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.</p> <p><strong>Publiceren volgens een schema ongeacht de inhoud.</strong> Maandelijkse notes zonder inhoud leren mensen dat jullie notes ruis zijn. Publiceer wanneer er iets te zeggen is. De changelog dekt de rest.</p> <h2>Degene die echt moeilijk is</h2> <p>De changelog en de aankondiging synchroon houden, zonder alles dubbel te schrijven.</p> <p>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 <a href="https://changeloop.dev/changelog-tools">changelog-tools</a> dekt wat daarvoor beschikbaar is, inclusief de tools waarmee we concurreren, en de pagina <a href="https://changeloop.dev/beamer-alternative">Beamer-alternatief</a> is de eerlijke vergelijking tegenover de widget waarmee de meeste teams beginnen.</p> <p>De <a href="https://changeloop.dev/release-notes-template">release notes template</a> is waar de selectiestap leeft zodra de entries bestaan.</p> <h2>Als je er maar één invoert</h2> <p>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.</p> <h2>FAQ</h2> <p><strong>Zouden release notes screenshots moeten hebben?</strong> 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.</p> <p><strong>Hoe schrijf je release notes voor een breaking change?</strong> 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 <a href="https://changeloop.dev/blog/nl/breaking-changes/">wat is een breaking change</a>.</p> <p><strong>Zouden release notes door engineering of marketing geschreven moeten worden?</strong> 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.</p> <p><strong>Wat is het ideale format voor release notes?</strong> Eerst de items met een deadline, dan de nieuwe mogelijkheden, dan de verbeteringen, dan een lijst van elk één regel met de rest. De <a href="https://changeloop.dev/release-notes-template">release notes template</a> is dat format als invulpagina.</p> </article> </main></body></html>