Changelog-conventies
Changelog-conventies
Sectie met titel “Changelog-conventies”Deze pagina beschrijft het contract dat elke openbare NextPDF-repository volgt bij het vastleggen van wijzigingen en het publiceren van releases. Het is een referentie voor conventies; het definieert geen pakketgedrag. Releaseopmerkingen per pakket en versie staan in de eigen CHANGELOG.md van elke repository. Deze gedeelde regels houden de repository-overstijgende changelogsamenvatting consistent en voorkomen dat er informatie uitlekt.
Conventional Commits 1.0.0
Sectie met titel “Conventional Commits 1.0.0”Elk commitonderwerp gebruikt type(scope): description. Het type is een van deze waarden:
| Type | Betekenis | Zichtbaar voor gebruiker | Versie-effect |
|---|---|---|---|
feat | Nieuwe functionaliteit | ja | minor-verhoging |
fix | Gecorrigeerd gedrag | ja | patch-verhoging |
perf | Prestatieverbetering zonder gedragswijziging | ja | patch-verhoging |
refactor | Interne herstructurering zonder waarneembare wijziging | nee | geen |
docs | Alleen documentatie | nee | geen |
test | Alleen tests | nee | geen |
build / ci | Alleen build of pipeline | nee | geen |
chore | Onderhoud, afhankelijkheden of tooling | nee | geen |
revert | Terugdraaien van een eerdere commit | afhankelijk | afhankelijk |
Een breaking change markeer je met een ! na het type of de scope (feat(api)!: …) of met een BREAKING CHANGE:-footer. Beide markeringen verhogen de major-versie volgens Semantic Versioning. Leg een beveiligingsrelevante fix zo vast dat deze in de kolom Security van de samenvatting over alle repository’s heen kan verschijnen.
Semantic Versioning 2.0.0
Sectie met titel “Semantic Versioning 2.0.0”Versieverhogingen worden mechanisch bepaald. Een release met een breaking change is een major. Een release zonder breaking change maar met een feat is een minor. Een release zonder breaking change of feat maar met een fix of perf is een patch. Pakketten van vóór 1.0 mogen volgens SemVer §4 de minor verhogen voor een breaking change. De commit draagt nog steeds de breaking-markering, zodat de samenvatting nauwkeurig blijft.
Keep a Changelog-groepering
Sectie met titel “Keep a Changelog-groepering”De CHANGELOG.md van elke repository volgt Keep a Changelog 1.1.0: vermeldingen worden per uitgebrachte versie gegroepeerd onder Added, Changed, Deprecated, Removed, Fixed en Security. Een [Unreleased]-sectie mag in de repository lopende notities bevatten, maar de repository-overstijgende samenvatting telt alleen getagde, uitgebrachte versies. Niet-uitgebracht werk verschijnt nooit in de openbare index.
Hoe de repository-overstijgende samenvatting wordt afgeleid (en informatielekkage voorkomt)
Sectie met titel “Hoe de repository-overstijgende samenvatting wordt afgeleid (en informatielekkage voorkomt)”De samenvattingstabel op de changelogindex wordt gegenereerd door de Conventional Commits-geschiedenis van elke repository op de laatste uitgebrachte tag in alleen-lezenmodus uit te lezen en de categorieën te tellen. De afleidingsregels zijn bewust beperkt, zodat interne details niet uitlekken:
- Aantallen, geen inhoud. Alleen het aantal commits per gebruikerszichtbaar type wordt gerapporteerd. Er wordt geen commitonderwerp, -tekst, -footer of -hash weergegeven.
- Alleen gebruikerszichtbare types.
docs,test,ci,choreenrefactorworden uitgesloten omdat ze niets wijzigen wat een pakketgebruiker waarneemt. - Alleen uitgebracht. Een commit telt pas mee zodra die deel uitmaakt van een getagde release van een openbaar pakket.
- Geen identificatoren. Interne verwijzingen naar issues, tickets, cycli, waves of werkitems die in een privé-commitscope kunnen voorkomen, worden nooit getoond, omdat de scopetekst zelf nooit wordt weergegeven. Alleen het type wordt gelezen.
- Geen automatiseringsattributie. Trailers van automatisering voor bijdragers worden niet gelezen of weergegeven.
Daarom is de openbare changelog een categoriesamenvatting met koppelingen naar de eigen CHANGELOG.md van elk pakket, geen geaggregeerde commitfeed. Door dit ontwerp lekt de samenvatting geen interne informatie. Gezaghebbende releaseteksten blijven bij het pakket dat ze beheert.