Keep a Changelog, écht geïmplementeerd
5 min lezen bijgewerkt op
Keep a Changelog is een conventie van één pagina voor een CHANGELOG.md: 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.
Olivier Lacan publiceerde Keep a Changelog in 2014 met een zin die beter is verouderd dan het meeste softwareproza: don’t let your friends dump git logs into changelogs. 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.
Wat vraagt Keep a Changelog?
Een CHANGELOG.md 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:
| Type | Voor | Wat het kost om weg te laten |
|---|---|---|
| Added | Nieuwe functies | Niets; niemand laat deze weg |
| Changed | Veranderingen in bestaand gedrag | Lezers ontdekken een gedragsverandering door een fout |
| Deprecated | Functies die worden verwijderd | Een verwijdering wordt een incident in plaats van een gepland moment |
| Removed | Functies verwijderd in deze release | Niemand onderscheidt een verwijdering van een bug |
| Fixed | Bugfixes | Niets; niemand laat deze ook weg |
| Security | Kwetsbaarheden | De ene lezer die ernaar zocht vindt hem niet |
Plus een Unreleased-sectie bovenaan, zodat er een plek is voor een entry zodra die wordt gemerged,
en zodat iedereen kan zien wat eraan komt.
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.
Welke delen van Keep a Changelog worden weggelaten?
De Unreleased-sectie, dan vier van de zes types, Security daaronder, in die volgorde.
Unreleased verdwijnt als eerste. 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. Changelog-automatisering gaat vooral over
deze sectie levend houden zonder dat iemand het hoeft te onthouden.
De zes types klappen in tot twee. 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 hoe deprecieer je een API.
Security stopt apart te zijn. 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.
Wat beantwoordt de spec niet?
Het is een bestandsformaat. Hij zegt niets over de vragen die je meteen tegenkomt na het adopteren ervan:
- Hoe komt iemand erachter? Een bestand in een repo bereikt bijdragers. Het bereikt geen klant die nooit GitHub heeft geopend.
- En producten zonder versies? 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.
- Wie schrijft de entry? De spec gaat ervan uit dat een mens dat doet. Hij zegt niet wanneer.
- En meerdere doelgroepen? 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. Changelog vs release notes is de splitsing die de spec je zelf laat maken.
Common Changelog, 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.
Kun je Keep a Changelog automatiseren zonder git logs te dumpen?
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.
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. Conventional commits behandelt de tweelaagse opdeling waar dit op leunt, en welke committypes op welke van de zes categorieën hierboven mappen. Ons overzicht changelog-tools dekt wat er bestaat voor de verzamelingshelft.
Waar stopt Keep a Changelog voldoende te zijn?
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.
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 changelog-voorbeelden publieke changelog-pagina’s verzamelt in plaats van repobestanden. Hoe je die entries omzet in iets waar mensen op terugkomen, behandelt een changelogpagina bouwen.
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.
FAQ
Is Keep a Changelog een standaard? 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.
Wat komt er in de Unreleased-sectie? 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.
Zou een changelog semantische versionering moeten gebruiken? 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.
Zouden securityfixes in de changelog moeten staan voordat ze publiek zijn? 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.
De technische beweringen in dit artikel zijn niet onafhankelijk gecontroleerd. Klopt er iets niet, laat het ons weten, dan corrigeren we het.