Kdo píše changelog, a kdo by měl

Zeptejte se týmu, kdo píše changelog, a upřímná odpověď bývá obvykle „kdokoli si vzpomene”, což je stejný způsob selhání, který vynucení záznamu changelogu v CI existuje napravit na mechanické úrovni. Ale vynucení existence záznamu nerozhodne, kdo je kvalifikovaná napsat dobrý, a týmy, které tuhle otázku přeskočí, mají tendenci vracet se výchozím způsobem k tomu, koho je nejsnazší přinutit, obvykle autorce PR, bez ověření, jestli je to opravdu osoba, která ho umí dobře napsat.

Proč není autorka PR automaticky nejlepší autorkou changelogu?

Protože zná implementaci, ne nutně dopad, a to jsou různé druhy znalostí. Kde se conventional commits zastavují rozebírá tuhle mezeru ze strany commit zprávy: fix(auth): reject expired refresh tokens je správně a zákaznici to neřekne nic, a ta, kdo tu opravu napsala, je často osoba nejméně vybavená ji přeložit, protože přemýšlela v pojmech té chyby celé hodiny a ztratila vnější pohled na to, co uživatelka skutečně zažila. Je to stejný důvod, proč technické spisovatelky existují jako profese: přeložit implementaci na dopad je samostatná dovednost, nezávislá na tom, že věc postavila, a chce to praxi bez ohledu na to, jak dobrá je vývojářka v samotném kódu.

Znamená to, že by měl každý záznam psát místo toho produkt nebo podpora?

Ne, protože mají opačnou mezeru: vědí, na čem uživatelkám záleží, ale ne vždy co bylo skutečně vydáno, což produkuje záznamy čitelné, ale občas nesprávné rozsahem, tvrzení „teď podporuje X” pro funkci stále za flagem, nebo opravu popsanou jako kompletní, když pokrývá jen jeden ze tří případů. Způsob selhání záznamů psaných vývojářkami je nečitelný-ale-přesný; způsob selhání záznamů psaných PM je čitelný-ale-neověřený. Žádná role nevlastní obě poloviny toho, co dobrý záznam potřebuje.

Jak vlastně vypadá funkční model vlastnictví?

Návrh od kohokoli nejblíž ke změně, přezkoumaný kýmkoli nejblíž k uživatelce, s jednou jmenovanou osobou odpovědnou za finální formulaci místo toho, aby všichni předpokládali, že problémy zachytí někdo jiný. Návrh musí existovat a být přesný víc, než musí být dobrý; hrubá věta napsaná vývojářkou, která správně říká, co se změnilo, je lepší výchozí bod než vyleštěná, ale neověřená, protože přepsat kvůli srozumitelnosti je snazší než přepsat kvůli správnosti. Krok recenze je tam, kde PM nebo vedoucí podpory přečte návrh a položí jedinou otázku, která zachytí mezeru v čitelnosti: rozuměla bych tomu, kdybych neviděla kód.

Měla by být odpovědná vždy stejná osoba, nebo se to střídá?

Jmenovaná a stabilní porazí střídající se, přinejmenším pro finální schválení. Střídající se vlastnice znamená, že každý záznam kontroluje někdo, kdo znovu odvozuje konvence týmu od nuly, což je přesně způsob, jak hlas mezi záznamy plave a čtenářka si začne všímat, že changelog napsal výbor. Jedna osoba, nebo velmi malá stabilní skupina, hromadí úsudky v čase, kdy říct „vylepšeno” versus pojmenovat konkrétní číslo, kdy oprava potřebuje vlastní záznam versus složit do dávky, a tenhle úsudek má větší hodnotu než rovnoměrné rozdělení práce.

Návrh (vývojářka, z PR):
"Fixed pagination cursor not respecting the `sort` param
in some edge cases."

Přezkoumáno (vlastnice changelogu, ověřeno proti skutečnému PR):
"Opraveno: exporty seřazené podle data mohly vracet
výsledky mimo pořadí za první stránkou. Teď konzistentní
napříč všemi stránkami."

Potřebuje malý tým tolik procesu kvůli jednomu řádku textu?

Ne role jako oddělené osoby, ale dva kroky pořád záleží i sólo. Jednočlenný tým je zároveň vývojářka i recenzentka, a disciplína, která na tom měřítku přežije, je udělat recenzi jako samostatný mentální průchod, ne skočit přímo od napsání opravy k publikování jejího popisu na jeden nádech. Past v malém měřítku je úplné přeskočení druhého průchodu, ne chybějící druhá osoba, protože nikdo zvenčí ho nevynucuje, a mezera v přesnosti, kterou má ten průchod zachytit, nezmizí jen proto, že stejná osoba by teoreticky mohla všimnout vlastního slepého místa.

Co se stane, když nikdo neodpovídá za finální záznam?

Changelog degraduje nerovnoměrně místo toho, aby otevřeně selhal, což je horší, protože si toho nikdo nevšimne, dokud na to čtenářka neupozorní. Některé záznamy zůstávají ostré, protože té, kdo je psala, na tom záleželo; jiné se stanou vágní, „různá vylepšení a opravy chyb”, protože ten, kdo je psal, spěchal a nikdo to nezachytil před zveřejněním. Formátová omezení Keep a Changelog zachytí strukturální drift, chybějící data, špatné kategorie, ale nic v šabloně nezachytí vágní záznam, který je technicky dobře naformátovaný, což je přesně mezera, kterou má jmenovaná vlastnice uzavřít.

FAQ

Měla by být vlastnice changelogu inženýrská role, nebo produktová? Obě mohou fungovat, pokud má osoba technickou plynulost ověřit rozsah i dostatečný odstup od implementace, aby psala pro vnější čtenářku; titul záleží méně než to, jestli dokáže obě poloviny, nebo ví, koho se zeptat na polovinu, kterou sama nezvládne.

Hodí se rotující rozvrh ve stylu pohotovosti pro vlastnictví changelogu? Pro objem někdy, pokud je tým příliš malý na to, aby jedna osoba kontrolovala všechno; pro hlas a úsudek ne, protože to je přesně to, co rotace narušuje. Rotace, která sdílí zátěž psaní návrhů při zachování jedné stabilní recenzentky, získá výhodu bez driftu.

Jaký je nejrychlejší signál, že s aktuálním nastavením vlastnictví něco není v pořádku? Záznamy přesné, ale nečitelné, nebo čitelné, ale nesprávné rozsahem, ve vzoru, který sleduje, kdo je napsal. Pokud kvalita koreluje s autorkou místo toho, aby zůstávala konzistentní, mezera je ve vlastnictví, ne v dovednosti psát.

Snižuje automatizace, jak moc na vlastnictví záleží? Snižuje, kolik psaní je potřeba, ne kolik úsudku je potřeba. Automatizace changelogu rozebírá, co může pipeline bezpečně generovat, formátování, publikování, cross-posting; formulace, seskupování a to, co se počítá jako hodné zmínky, zůstávají lidská rozhodnutí bez ohledu na to, kolik z pipeline je automatizováno.

Co když se autorka PR a recenzentka neshodnou na formulaci? Rozhoduje recenzentka, protože otázka, na kterou odpovídá, rozuměl by tomu vnější čtenář, je přesně ta, kterou má tahle role chránit. To neznamená, že pohled vývojářky je bezcenný: pokud je neshoda o přesnosti, ne o formulaci, recenzentka ustoupí, protože rozsah je polovina, kterou má správně mít autorka. Rozdělení dvou druhů neshody, formulace proti přesnosti, zastaví většinu z nich dřív, než se z toho stane spor.

Technická tvrzení v tomto článku nikdo nezávisle neověřil. Pokud tu něco nesedí, dej nám vědět a opravíme to.

Související na changeloop: Srovnání nástrojů pro changelog, Generátor changelogu