Changelog vs release notes: wat is het verschil?

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.

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.

Changelog vs release notes, naast elkaar

Wat is een changelog?

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 Keep a Changelog het grootste deel van zijn ene pagina aan structuur en bijna niets aan proza.

Wat zijn release notes?

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. Hoe schrijf je release notes gaat over de selectie en de formulering.

Heb je zowel een changelog als release notes nodig?

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 /changelog-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.

De splitsing wordt de moeite waard wanneer dit begint te gebeuren:

• Jullie changelog-entries zijn uitgegroeid tot uitleggende alinea’s die developers overslaan.
• Of het tegenovergestelde: jullie release-aankondigingen zijn dependency-updates gaan opsommen.
• Support kopieert entries naar e-mails en herschrijft ze onderweg.
• Iemand vraagt om “alleen de breaking changes” en jullie kunnen daar niet op filteren.

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.

Eén bron, twee weergaven

De fout is ze als twee documenten te behandelen. Het zijn twee weergaven op dezelfde set veranderingen.

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.

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. Changelog-automatisering 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.

Als je maar tijd hebt voor één

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.

Houd het in een vast formaat zodat de afleiding mogelijk blijft. Onze pagina changelog-voorbeelden verzamelt entries van teams die dit goed doen, en de release notes template is de vorm die we gebruiken om een set entries om te zetten in iets dat de moeite waard is om te versturen.

Een noot over naamgeving

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.

Op welk oppervlak het resultaat terechtkomt is een aparte beslissing, behandeld in een changelogpagina bouwen.

FAQ

Is een changelog hetzelfde als release notes? 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.

Kunnen release notes uit een changelog worden gegenereerd? 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.

Waar zou een changelog moeten leven? Ergens permanents en koppelbaars dat de lezer kan bereiken zonder repository: een /changelog-pagina, een docsite, of een feed die op meerdere plekken wordt weergegeven. Een CHANGELOG.md alleen bereikt bijdragers, geen klanten.

Zou een changelog interne veranderingen moeten bevatten? 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.

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

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