Release notes voorbeelden voor elk soort wijziging

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.

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.

De technische beweringen in dit artikel zijn niet onafhankelijk gecontroleerd. Klopt er iets niet, laat het ons weten, dan corrigeren we het.

Meer op changeloop: Sjabloon voor release notes, Changelog-voorbeelden