Wie schrijft de changelog, en wie zou dat moeten doen

Vraag een team wie de changelog schrijft en het eerlijke antwoord is meestal “wie het zich herinnert”, wat hetzelfde faalpatroon is dat een changelog-item afdwingen in CI bestaat om op mechanisch niveau op te lossen. Maar het afdwingen dat een item bestaat beslist niet wie gekwalificeerd is om er een goede te schrijven, en teams die die vraag overslaan vallen doorgaans standaard terug op wie het makkelijkst te verplichten is, meestal de PR-auteur, zonder te checken of dat ook echt de persoon is die het goed kan schrijven.

Waarom is de PR-auteur niet automatisch de beste changelog-schrijver?

Omdat ze de implementatie kent, niet per se de impact, en dat zijn verschillende soorten kennis. Waar stoppen conventional commits behandelt deze kloof vanaf de commitbericht-kant: fix(auth): reject expired refresh tokens is correct en vertelt een klant niets, en wie die fix schreef is vaak de persoon die het minst is toegerust om het te vertalen, omdat ze uren in termen van de bug heeft gedacht en het buitenperspectief kwijt is van wat een gebruiker daadwerkelijk heeft ervaren. Dit is dezelfde reden waarom technisch schrijvers als beroep bestaan: het vertalen van implementatie naar impact is een aparte vaardigheid ten opzichte van het bouwen van het ding zelf, en het vergt oefening ongeacht hoe goed de engineer zelf in de code is.

Betekent dat dat product of support elk item in plaats daarvan zou moeten schrijven?

Nee, want zij hebben de omgekeerde kloof: ze weten wat belangrijk is voor gebruikers maar niet altijd wat er daadwerkelijk is uitgeleverd, wat items oplevert die leesbaar maar af en toe verkeerd zijn qua omvang, een “ondersteunt nu X”-claim voor een feature die nog achter een flag zit, of een fix beschreven als compleet terwijl die maar één van drie gevallen dekt. Het faalpatroon van door ontwikkelaars geschreven items is onleesbaar-maar-accuraat; het faalpatroon van door PM’s geschreven items is leesbaar-maar-ongeverifieerd. Geen enkele rol bezit beide helften van wat een goed item nodig heeft.

Hoe ziet een werkend eigenaarschapsmodel er eigenlijk uit?

Een concept van wie het dichtst bij de verandering staat, gereviewd door wie het dichtst bij de gebruiker staat, met één benoemde persoon verantwoordelijk voor de uiteindelijke formulering in plaats van dat iedereen aanneemt dat iemand anders problemen zal opvangen. Het concept moet vooral bestaan en accuraat zijn, meer dan dat het goed moet zijn; een ruwe, door een ontwikkelaar geschreven zin die correct zegt wat er is veranderd is een beter startpunt dan een gepolijste maar ongeverifieerde, omdat herschrijven voor duidelijkheid makkelijker is dan herschrijven voor correctheid. De reviewstap is waar een PM of supportlead het concept leest en de ene vraag stelt die de leesbaarheidskloof vangt: zou ik dit begrijpen als ik de code niet had gezien.

Zou altijd dezelfde persoon verantwoordelijk moeten zijn, of roteert dat?

Benoemd en stabiel wint van roterend, in ieder geval voor de uiteindelijke goedkeuring. Een roterende eigenaar betekent dat elk item wordt gereviewd door iemand die de conventies van het team vanaf nul opnieuw afleidt, wat precies is hoe de stem van item tot item afdrijft en een lezer begint te merken dat de changelog door een comité is geschreven. Eén persoon, of een zeer kleine stabiele groep, verzamelt de afwegingen na verloop van tijd, wanneer je “verbeterd” zegt versus het specifieke getal noemt, wanneer een fix zijn eigen item nodig heeft versus opgaat in een batch, en dat oordeel is meer waard dan het werk gelijkmatig verdelen.

Concept (ontwikkelaar, uit de PR):
"Fixed pagination cursor not respecting the `sort` param
in some edge cases."

Gereviewd (changelog-eigenaar, getoetst aan de echte PR):
"Opgelost: op datum gesorteerde exports konden resultaten
buiten volgorde retourneren voorbij de eerste pagina.
Nu consistent op alle pagina's."

Heeft een klein team zoveel proces nodig voor één regel tekst?

Niet de rollen als aparte personen, maar de twee stappen tellen nog steeds, zelfs solo. Een team van één persoon is zowel de ontwikkelaar als de reviewer, en de discipline die op die schaal overleeft is de review als een aparte mentale pas doen, niet direct van het schrijven van de fix naar het publiceren van een beschrijving ervan in dezelfde adem springen. De valkuil op kleine schaal is de tweede pas helemaal overslaan, niet het ontbreken van een tweede persoon, omdat niemand van buitenaf het afdwingt, en de nauwkeurigheidskloof die die pas bestaat om te vangen verdwijnt niet alleen omdat dezelfde persoon in theorie haar eigen blinde vlek zou kunnen opmerken.

Wat gebeurt er als niemand verantwoordelijk is voor het uiteindelijke item?

De changelog verslechtert ongelijkmatig in plaats van compleet te falen, wat erger is omdat niemand het merkt totdat een lezer het aanwijst. Sommige items blijven scherp omdat wie ze schreef erom gaf; andere worden vaag, “diverse verbeteringen en bugfixes”, omdat wie ze schreef snel bezig was en niemand het opmerkte voor publicatie. De formaatbeperkingen van Keep a Changelog vangen structurele drift, ontbrekende datums, verkeerde categorieën, maar niets in een template vangt een vaag item dat technisch goed geformatteerd is, wat precies de kloof is die een benoemde eigenaar er is om te dichten.

FAQ

Zou de changelog-eigenaar een engineering- of een productrol moeten zijn? Beide kunnen werken als de persoon zowel technische vaardigheid heeft om de omvang te verifiëren als genoeg afstand van de implementatie om voor een buitenstaande lezer te schrijven; de titel telt minder dan of ze beide helften kan doen, of weet aan wie te vragen voor de helft die ze niet kan.

Is een roterend, wachtdienst-achtig schema ooit geschikt voor changelog-eigenaarschap? Voor volume soms, als het team te klein is voor één persoon om alles te reviewen; voor stem en oordeel niet, want dat is precies wat rotatie eroderen. Een rotatie die de conceptlast deelt terwijl één stabiele reviewer behouden blijft krijgt het voordeel zonder de drift.

Wat is het snelste teken dat er iets mis is met de huidige eigenaarschapsopzet? Items die accuraat maar onleesbaar zijn, of leesbaar maar verkeerd qua omvang, in een patroon dat volgt wie ze schreef. Als kwaliteit correleert met de auteur in plaats van consistent te blijven, is eigenaarschap de kloof, niet schrijfvaardigheid.

Vermindert automatisering hoeveel eigenaarschap ertoe doet? Het vermindert hoeveel schrijven nodig is, niet hoeveel oordeel nodig is. Changelog-automatisering behandelt wat een pipeline veilig kan genereren, opmaak, publicatie, cross-posting; formulering, groepering en wat telt als vermeldenswaard blijven menselijke beslissingen ongeacht hoeveel van de pipeline geautomatiseerd is.

Wat als de PR-auteur en de reviewer het oneens zijn over de formulering? Het is aan de reviewer, want de vraag die ze beantwoorden, zou een buitenstaande lezer dit begrijpen, is precies degene die de rol moet beschermen. Dat maakt de kijk van de engineer niet waardeloos: als het meningsverschil over accuraatheid gaat in plaats van over formulering, geeft de reviewer toe, want omvang is de helft die de auteur moet kloppen. De twee soorten meningsverschil scheiden, formulering versus accuraatheid, voorkomt dat de meeste hiervan een impasse worden.

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-tools vergeleken, Changelog-generator