De changeloop-blog
Release notes in de praktijk
Twee dingen waar we veel over nadenken: hoe je release notes schrijft die iemand leest, en hoe je stopt met een changelog met de hand bijhouden. Geen nieuwsbrief, geen registratie. Alleen de artikelen.
Bugfix release notes schrijven die mensen gebruiken
Bugfix release notes werken als elke entry het symptoom, de getroffenen en de volgende stap noemt. Voor-en-na-herschrijvingen en regels voor beveiliging.
Release notes in de praktijk7 min lezen
Klantfeedback vragen in een softwareproduct
Stel één concrete vraag direct nadat de gebruiker iets deed, waar hij werkt. Kant-en-klare formuleringen per moment, en de slechte vragen om te mijden.
Feedbackloop7 min lezen
Product roadmap voorbeelden: zes formats en hun valkuilen
Zes product roadmap voorbeelden met echte items: Now/Next/Later, kwartaal, thema, uitkomst, publiek en release. Voor wie elk past, en waar het misgaat.
Feedbackloop7 min lezen
Releasemanagementproces voor teams die vaak uitbrengen
Een releasemanagementproces voor softwareteams in zeven stappen, met per stap een eigenaar en exitcriteria, plus de DORA-metrics en een extra KPI.
Engineering7 min lezen
Release notes voorbeelden voor elk soort wijziging
Release notes voorbeelden voor een feature, fix, breaking change, beveiligingsfix, deprecatie, app-storenote en interne note, met telkens waarom het werkt.
Release notes in de praktijk7 min lezen
Stripe API-versionering: hoe het werkt en wat je kopieert
Stripe API-versionering pint elk account op een gedateerde versie en laat elk verzoek die overschrijven. Hoe het werkt en wat een kleine API kan overnemen.
API-wijzigingen7 min lezen
Wie schrijft de changelog, en wie zou dat moeten doen
Wie schrijft de changelog? De PR-auteur weet wat er veranderde, de PM waarom het telt. Alleen schrijft geen van beiden een item dat klanten helpt.
Engineering5 min lezen
Noodrelease notes: schrijven onder echte tijdsdruk
Een door een incident gedreven release heeft notes nodig in minuten, niet dagen, en het gebruikelijke schrijfproces gaat uit van tijd die je niet hebt.
Release notes in de praktijk5 min lezen
Protobuf breaking changes: wat overleeft op de wire
Protobuf breaking changes gebeuren op de wire, niet in de URL. Sommige gRPC-veldwijzigingen zijn gratis, andere breken elke client stilletjes.
API-wijzigingen6 min lezen
Changelog-bestandsformaten: JSON, YAML of gewoon Markdown
Het bestandsformaat van een changelog bepaalt of het een pagina en widget kan voeden, of alleen een mens helpt. Markdown, JSON en YAML kosten anders.
Engineering5 min lezen
Dubbele featureverzoeken: zonder de stem te verliezen
Dubbele featureverzoeken groeperen beschermt de telling. Ze achteloos samenvoegen verliest de formulering die er een nuttig maakte, het kleinere verlies.
Feedbackloop5 min lezen
GraphQL-deprecatie zonder versienummer
GraphQL heeft geen v1 of v2 in de URL. Velden worden per stuk gedeprecieerd via een directive op een gedeeld schema. Wat een changelog schuldig is.
API-wijzigingen5 min lezen
Hoe je een API-migratiegids schrijft
Een API-migratiegids maakt van een breaking change een checklist in plaats van een storing. Wat hij nodig heeft, en waarom een regel niet genoeg is.
API-wijzigingen5 min lezen
Een changelog-check voor GitHub Actions
Een changelog-check in GitHub Actions weigert een merge zonder item, want een stap die op geheugen leunt faalt voorspelbaar. En wat die check zelf breekt.
Engineering5 min lezen
Featureverzoek afwijzen zonder de klant te verliezen
De cirkel sluiten betekent meestal zeggen dat iets uitkwam. De moeilijke helft is nee zeggen, zonder daarbij de relatie met de klant te schaden.
Feedbackloop5 min lezen
Feature flag release notes: wat je zegt, en wanneer
Feature flag release notes scheiden merge en release, want met een flag vallen ze niet samen. Sluit je de loop te vroeg, dan meld je iets onzichtbaars.
Feedbackloop5 min lezen
Featureverzoeken bijhouden zonder ze kwijt te raken
Het bijhouden van featureverzoeken faalt meestal op twee manieren: ze komen nergens terecht, of ergens waar niemand kijkt. Een systeem dat beide overleeft.
Feedbackloop6 min lezen
Wanneer een featureverzoek eigenlijk een bugreport is
Een supportticket dat om een nieuwe instelling vraagt kan een workaround voor een verborgen bug zijn. Het verkeerde label stuurt het naar de verkeerde rij.
Feedbackloop5 min lezen
Supporttickets vs. featureverzoeken: wat vertrouw je?
Een supportticket en een featureverzoekbord meten verschillende dingen, en een piek in het ene gelijkstellen aan het andere levert foute prioriteiten op.
Feedbackloop5 min lezen
Git-tags, releases en je changelog
Een git-tag, een release en een changelog-regel zijn drie registraties van één gebeurtenis. Ze verwarren laat de changelog afdrijven. Hoe ze samenkomen.
Engineering5 min lezen
Interne API-changelogs: wat verandert er
Een publieke API-changelog heeft een publiek dat je niet direct bereikt. Een interne heeft lezers twee verdiepingen verderop, en dat verandert de inhoud.
API-wijzigingen5 min lezen
Interne release notes: wie het nog meer moet weten
Support en sales horen over een lancering meestal van een verwarde klant. Interne release notes lossen dat op, in een andere vorm dan de klantgerichte.
Release notes in de praktijk5 min lezen
Release notes voor mobiele apps: wat de limiet wegsnijdt
App Store en Play Store geven een paar zichtbare regels en geen links. Wat op een web-changelog werkt, breekt op dat budget, dus maak de keuzes bewust.
Release notes in de praktijk5 min lezen
Monorepo-changelogs: één, of één per package?
Een monorepo kan één changelog voor de hele repo hebben of één per package, en de verkeerde keuze maakt elke release te rommelig of te versnipperd.
Engineering5 min lezen
Hoe je een nieuwe feature aankondigt (zonder stilte)
De meeste featureaankondigingen sterven in een kanaal dat niemand twee keer leest. Waar je aankondigt, wat je eerst zegt, wie je moet bereiken.
Release notes in de praktijk5 min lezen
Enterprise release notes: wat verandert voor één account
Enterprise release notes voor een klant op een private build moeten bij zijn instantie passen. Verkeerd afstemmen lekt de roadmap of verwart de support.
Release notes in de praktijk5 min lezen
Featureverzoeken prioriteren die zich opstapelen
Een bijgehouden backlog laat de lastige vraag open: welk verzoek gaat eerst. De frameworks die werken, waar ze breken en wat een stemmentelling verbergt.
Feedbackloop5 min lezen
Semantic versioning en je changelog
Semantic versioning vertelt hoeveel pijn een release kan doen, nog voor je een woord changelog leest. Wat elk cijfer belooft en wat een regel schuldig is.
Engineering5 min lezen
De API sunset header, en wanneer je er een moet sturen
De API sunset header vertelt een client wanneer een versie stopt met antwoorden, anders dan een deprecatiebericht. Wat RFC 8594 dekt en wat brownouts doen.
API-wijzigingen5 min lezen
Webhook-changelogs: de breaking change die niemand vroeg
Een webhook-payloadwijziging breekt stilletjes, omdat niemand haar kan afwijzen. Wat een payloadwijziging breaking maakt, en hoe je hem versieert.
API-wijzigingen5 min lezen
Changelog: wat is het? Met een voorbeeld
Een changelog is het gedateerde overzicht van wat er in een product veranderde. Met voorbeeld, het verschil met release notes en waar hij hoort te staan.
Release notes in de praktijk5 min lezen
API-changelog: wat je publiceert, en wie het leest
Een API-changelog wordt gelezen door mensen die beslissen of hun code volgende maand nog werkt. Wat elk item hun schuldig is, waar het staat en abonneren.
API-wijzigingen6 min lezen
Een changelogpagina bouwen die mensen blijven volgen
Een changelogpagina is de moeite waard als iemand erop terugkomt. Waar hij moet leven, wat elk item nodig heeft, feeds en markup, en waar de widget past.
Engineering6 min lezen
De product-update e-mailtemplate die gelezen wordt
De product-update e-mail die gelezen wordt, ging naar iemand die erom vroeg. Een template, de vier soorten e-mail, werkende onderwerpregels en toestemming.
Release notes in de praktijk6 min lezen
Hoe deprecieer je een API zonder developers te verliezen
Deprecatie is een belofte met een datum erop. Het tijdschema, de berichtsjabloon, de response-headers, en de stap die een sunset behoedt voor een incident.
API-wijzigingen6 min lezen
Beste practices voor API-versionering, voor aanroepers
Versioneer alleen wat breekt, zet de versie zichtbaar, en houd de oude versie actief tot een datum. Vier schema's vergeleken op wat ze van je vragen.
API-wijzigingen7 min lezen
Breaking changes: wat telt en hoe je er een uitbrengt
Een breaking change is elke wijziging die een correcte aanroeper niet overleeft. Wat telt, wat niet, hoe je er in CI een vangt en hoe je er een uitbrengt.
API-wijzigingen9 min lezen
De feedback-loop sluiten vanuit de changelog
Een feedback-loop sluit als de vrager weet: uitgebracht. De loop in vier stappen, waar hij breekt, en waarom de changelog de juiste plek is om te sluiten.
Feedbackloop8 min lezen
Feature-request-template die changelog wordt
Een feature-verzoek is alleen nuttig als je het terugvindt bij uitbrengen. De template, de labels die hem routeren, en de velden die de changelog leest.
Feedbackloop6 min lezen
Publieke roadmap uit je issue tracker, drie kolommen
Een publieke roadmap is een belofte over de toekomst. Houd hem klein, voed hem uit je issues, en verplaats elk item met een label op de bijbehorende issue.
Feedbackloop6 min lezen
Changelog-automatisering, en haar grenzen
Automatiseer verzameling, opmaak en publicatie. Automatiseer geen selectie of formulering. Waar de grens ligt en wat er gebeurt als hij verschuift.
Engineering6 min lezen
Changelog vs release notes: wat is het verschil?
Een changelog is een doorlopend register voor wie iets opzoekt. Release notes zijn een gecureerd bericht voor wie beslist of het telt. De verdeling.
Release notes in de praktijk5 min lezen
Van conventional commits naar een changelog
Conventional commits maken een changelog afleidbaar. Ze maken hem niet leesbaar. Wat de conventie oplevert, waar hij stopt, en hoe je de kloof overbrugt.
Engineering5 min lezen
Hoe schrijf je release notes die mensen echt lezen
«Bugfixes en prestatieverbeteringen» is geen release note. De vraag die elke entry moet beantwoorden, plus het herschrijven van een echte release note.
Release notes in de praktijk6 min lezen
Keep a Changelog, écht geïmplementeerd
De spec is één pagina en kost tien minuten om te lezen. Bij implementatie glijden teams af. Wat hij zegt, wat hij openlaat, en waar het misgaat.
Engineering5 min lezen
Beste practices voor release notes die het waard zijn
De meeste lijsten met beste practices zijn stijladvies. Deze veranderen wat de lezer doet, plus drie populaire regels die pure cargocultus zijn.
Release notes in de praktijk6 min lezen