Git-tags, releases en je changelog

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?

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.

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-generator, Documentatie voor ontwikkelaars