Changelogs spårbara till riktiga commits

En changelog är ett faktapåstående om vad en release gör med sina användare. Läs en bra en och du kan inte avgöra om den är sann — varje generator gör posterna snygga, och nästan ingen gör dem verifierbara. AI-skrivna changelogs har dokumenterade felmönster: hittade-på poster, hallucinerade versionsnummer och datum, breaking changes begravda eller borttappade, vänliga omskrivningar som glider ifrån vad koden faktiskt gjorde. Vi driver en katalog som benchmarkar Claude-skills på heltid, så vi byggde disciplinlagret som blockerar var och en av dem — och mätte det sedan mot fyra riktiga open source-releaser.

Resultatet är changelog-discipline, och det här inlägget publicerar dess siffror i sin helhet, inklusive de gånger den förlorade. Den är gratis och MIT-licensierad: github.com/Skillproofdev/changelog-discipline.

Luckan: ärlighet och läsbarhet levereras i olika produkter

Innan vi skrev en rad kartlade vi 101 changelog- och release notes-skills i vårt dataset på 16 000 skills, plus de fristående verktygen — git-cliff, release-please, conventional-changelog. De två halvorna av en bra changelog lever i olika produkter och överlappar aldrig.

Mekaniska generatorer (git-cliff och liknande) är spårbara genom sin konstruktion: varje rad kommer från en commit. Men de ser bara conventional commits, så allt som inte matchar feat:/fix: faller bort i tysthet, och de läses som en analyserad git-logg, för det är vad de är. AI-generatorer skriver vackert — språk om användarpåverkan, ren gruppering — men de verifierar ingenting, så de hittar på poster, myntar versionsnummer och begraver breaking changes när releasen ser renare ut utan dem. Ingen tvingar fram både ärlighet och läsbarhet, och ingen tvingar fram träffgrad för breaking changes ovanpå det. Den tredje egenskapen är den som faktiskt gör ont när den saknas: en borttappad breaking change är det enda changelog-felet du inte kan reparera i efterhand.

Åtta regler, tre ingen annan tvingar fram

Skillen är en uppsättning hårda regler (hela SKILL.md). Det välbekanta: Keep-a-Changelog-gruppering, språk om användarpåverkan som aldrig breddar ett påstående bortom diffen, versioner och datum lästa från riktiga taggar istället för skrivna ur minnet, och en obligatorisk egengranskning innan leverans. Delarna ingen annan tvingar fram:

1. Härledd från git, aldrig från minnet. Intervallet löses upp och läses — git log, plus diffar där ämnesraderna är luddiga — innan en enda post skrivs. Ingen repo-åtkomst betyder ingen changelog, ingen gissning från "vad vi jobbade på."
2. Varje rad spåras till en riktig commit eller PR. En spårningskarta byggs först; en post som inte kan peka på en commit skickas inte, och varje citerat (#123) eller (abc1234) måste finnas i den faktiska historiken.
3. Breaking changes jagas, väntas inte in. Inte bara BREAKING CHANGE:-fotnoter — borttagna API:er, omdöpta flaggor, ändrade standardvärden hittade genom att läsa diffen. De kommer först, märkta BREAKING, med en rads migreringsanteckning.

Benchmarket: fyra riktiga releaser, poängsatta mot mänskliga changelogs

Vi valde fyra open source-repon med handkurerade changelogs som facit och valde ett releasat taggintervall vardera, hämtat vid de fastnaglade taggarna: Django 5.2→6.0 (störst, 404 commits i det poängsatta setet), Tailwind CSS v4.0.0→v4.1.0, FastAPI 0.116.2→0.117.0 (en noll-breaking-fälla — dess kurerade anteckningar har ingen breaking-sektion, så varje post presenterad som breaking är en fabrikation), och curl 8.14.1→8.15.0. Två agenter fick identisk prompt och samma repo; enda skillnaden var om agenten läste SKILL.md först. Vi poängsatte commit-täckning, fabricerade poster (mekaniskt verifierade mot riktiga hashar och datum), träffgrad för breaking changes, formatefterlevnad och blind läsbarhet.

Intervall	Gren	Spårbar commit-täckn.	Fabricerad	Breaking först?	Format (0–6)
Tailwind	bas	0/164 (0%)	0	nej	3
	skill	143/164 (87%)	0	ja	5
Django	bas	23/404 (6%)	0	nej	3
	skill	234/404 (58%)	0	ja	6
curl	bas	22/278 (8%)	0	ja	3
	skill	59/278 (21%)	0	ja	6
FastAPI	bas	12/18 (67%)	0	ej relevant	4
	skill	9/18 (50%)	0	ej relevant	6

Där disciplinen syns vinner skillen tydligt. Spårbarhet är dess kärntes och den dominerar: 87% mot 0% på Tailwind, 58% mot 6% på Django. Basagenten skriver flytande prosa som beskriver massor av riktiga ändringar — den kan bara inte spåra dem tillbaka till commits, vilket är exakt gapet skillen finns för att stänga. Formatefterlevnaden var 30/36 över skillens fyra körningar mot 13/36 för basen; varje basutdata använde rubriker som inte följde Keep-a-Changelog ("Features", "Notable bug fixes"), tappade ISO-datumet och klistrade på ett anteckningsefterord. Och på placering av breaking changes, över de tre intervall som faktiskt har breaking changes, satte skillen dem först och märkte dem BREAKING i alla tre; basen gjorde det i en (curl).

Ärligt talat: huvudmåttet slutade oavgjort

Siffran vi mest ville flytta — fabricerade poster — flyttade inte. Den var 0 för alla åtta utdata. Oavgjort. Varje #-citering löstes till en riktig referens (upp till 195 av dem i en enda skillkörning), inga hittade-på versioner eller datum, och varje stickprovskontrollerat prosapåstående var commit-belagt, inklusive Djangos 11 CVE:er. Anledningen är enkel och vi klär inte upp den: på den här korpusen var basagenten redan disciplinerad nog att inte hitta på poster, så skillens fabrikationsgaranti höll men testades aldrig på riktigt. Vi rapporterar oavgörandet istället för att gömma det.

Där skillen förlorade — publicerat ändå

Vår metodik kräver att förlusterna redovisas bredvid vinsterna, och det fanns riktiga sådana.

Basen vann ren läsbarhet på de två stora repona. På curl och Django föredrog den enda blinda bedömaren basutdatan — dess kurerade berättarstil, med en dedikerad CVE-sektion på Django, läses bättre än skillens uttömmande 230-radersblock i Keep-a-Changelog-format. Bedömaren kunde inte se att basversionen var ospårbar och spred ut sina breaking changes; på läsbarhet ensamt vann basen. Skillen byter bort en del läsbarhet på stora releaser mot struktur och ärlighet, och det bytet syns.

Basen slog till och med skillen på spårbar täckning för FastAPI — 67% mot 50%. Det här är vårt favoritresultat, för skillen hade rätt i att förlora det: basen citerade tre extra interna commits (en mypy-uppgradering, en cacheändring för beroenden, en pydantic.mypy-justering) som skillen korrekt strök som icke-användarrelevanta. Måttet belönade basen för att lista brus en användare inte borde se. Och på Tailwinds träffgrad för breaking changes slog basen skillen 4/7 mot 3/7 genom att formulera en avveckling i prosa som skillen arkiverade under Added — formuleringstur på en korpus där ingen commit-ämnesrad säger "deprecate."

Två ärliga förbehåll om själva benchmarket: den blinda preferenspoängen använde 1 bedömare, inte de 3 vi specificerar, så den är underdimensionerad. Och tokenkostnad per körning fångades inte den här gången — skillgrenen betalar dessutom för att läsa SKILL.md, och vi kan ännu inte säga dig hur mycket.

Installation

git clone https://github.com/Skillproofdev/changelog-discipline ~/.claude/skills/changelog-discipline

Starta om Claude Code. Den triggas av "skriv en changelog", "release notes för v2.3", "uppdatera CHANGELOG.md" och "vad ändrades mellan 1.4 och 2.0" — och håller sig undan från blogginlägg, marknadsföringstext och skrivande av commit-meddelanden. Den ansluter till research-discipline, som minskar vad ett researchat svar har fel om, och token-discipline, som minskar vad din kontext kostar, i vår benchmarkade disciplinserie.

FAQ

Hur skiljer sig det här från git-cliff eller conventional-changelog? De är spårbara genom sin konstruktion men ser bara conventional commits, så icke-konformt arbete faller bort i tysthet, och de läses som en analyserad logg. Den här skillen läser hela intervallet — diffar inkluderade, inte bara commit-ämnesrader — och skriver språk om användarpåverkan samtidigt som den fortfarande kräver att varje rad spåras till en riktig commit. Spårbarhet och läsbarhet, vilket inget enskilt verktyg i vår kartläggning tvingade fram tillsammans.

Dumpar den bara git-loggen med snyggare formuleringar? Nej — tvärtom. Den mappar varje commit till antingen en post eller ett medvetet uteslutande, jagar breaking changes i diffen, grupperar enligt Keep-a-Changelog-rubriker och sätter breaking-poster först med en migreringsanteckning. På FastAPI korrekt strök den tre interna commits basagenten listade, vilket kostade den en täckningspoäng och var det rätta valet.

Hittar den på versionsnummer eller datum? Den är byggd för att inte göra det: versionsrubriken är det riktiga taggnamnet och datumet är taggens faktiska datum, läst via git i ISO-8601. Ej releasade intervall hamnar under ## [Unreleased] istället för att få ett myntat nummer. Över åtta benchmark-utdata, noll hittade-på versioner, datum eller PR-nummer.

Ska jag lita på benchmarket? Lita på det så långt det räcker, vilket vi säger rakt ut: fabrikationsmåttet blev en 0–0-oavgjort för att basagenten redan var ärlig på den här korpusen, läsbarhetspoängen använde en bedömare istället för tre, och tokenkostnad fångades inte. Vinsterna som är solida — spårbarhet, format, placering av breaking changes — är mekaniskt poängsatta mot de mänskliga changelogsen och reproducerbara. Hela bedömningen publicerar varje cell, inklusive förlusterna.