Changelog vs release notes: jaký je rozdíl?

Changelog je průběžný, kumulativní záznam všeho, co se změnilo, napsaný pro někoho, kdo něco hledá. Release notes jsou vybraná zpráva o jednom vydání, napsaná pro někoho, kdo se rozhoduje, zda ho to zajímá. Rozdíl je v publiku, ne ve formátování, a většina týmů potřebuje obojí: jedno jako referenci, druhé jako oznámení, odvozené ze stejných záznamů.

Většina týmů skončí s jedním z nich náhodou a s druhým na požádání. Začnete s changelogem, protože vývojářka chce záznam o tom, co bylo vydáno. O měsíce později se někdo z podpory zeptá, proč zákazníci nevěděli o funkci, která je živá od dubna, a teď potřebujete release notes.

Changelog vs release notes, vedle sebe

Co je changelog?

Changelog je chronologický, téměř úplný záznam toho, co se změnilo, nejnovější první, s každým záznamem typizovaným (added, changed, deprecated, removed, fixed, security) a datovaným. Jeho čtenář se už rozhodl, že ho to zajímá. Něco hledá: kdy se změnilo chování, zda je chyba opravena, která verze zavedla flag. Úplnost je celá hodnota, proto konvence Keep a Changelog tráví většinu své jediné stránky na struktuře a téměř nic na próze.

Co jsou release notes?

Release notes jsou selektivní zpráva, napsaná prózou, o jednom vydání. Jejich čtenář se ještě nic nerozhodl. Rozhoduje se, zda se ho toto vydání týká, a zda s tím musí něco udělat. Výběr je celá hodnota: release note, která vypisuje vše, je changelog s odstavci, a selhává čtenáře stejným způsobem, jakým changelog, který něco vynechává, selhává toho svého. Jak psát release notes je o výběru a formulaci.

Potřebujete changelog i release notes?

Potřebujete oba, jakmile vaše dvě publika začnou chtít různé věci; do té doby je jeden artefakt plnící obě práce správný. Malé týmy zveřejňují jednu stránku /changelog s krátkým odstavcem v čele každého záznamu, a nějakou dobu to slouží stejně dobře vývojářce hledající opravu i zákaznici procházející novinky. Rozdělení příliš brzy vám dá dvě věci k údržbě a jedna z nich zetle.

Rozdělení se vyplatí, když se toto začne dít:

• Vaše záznamy changelogu narostly do vysvětlujících odstavců, které vývojáři přeskakují.
• Nebo opak: vaše oznámení o vydáních začala vypisovat aktualizace závislostí.
• Podpora kopíruje záznamy do e-mailů a přepisuje je cestou.
• Někdo žádá «jen breaking changes» a vy je nemůžete odfiltrovat.

Poslední z toho je pravý signál. Pokud nikdo nedokáže odpovědět «co se změnilo, co se mě týká» bez přečtení všeho, máte jeden artefakt, který plní dvě práce špatně.

Jeden zdroj, dva pohledy

Chybou je zacházet s nimi jako se dvěma dokumenty. Jsou to dva pohledy na stejnou sadu změn.

Pište changelog průběžně, jeden záznam na významnou změnu, každý označený tím, čím je: fixed, added, changed, removed, deprecated, security. Udržujte záznamy dostatečně krátké, aby napsání jednoho nebyla rozhodnutí. Pak, v okamžiku vydání, jsou release notes výběr a přepis: vezměte záznamy, na kterých záleží člověku, seskupte je podle toho, co někomu umožňují udělat, a dejte důvod nahoru.

To má praktický důsledek. Pokud je changelog zdroj, musí to být strukturovaná data, ne ručně udržovaná stránka. Záznam potřebuje typ, datum, verzi, a způsob, jak říct, pro koho je. Jakmile to má, veřejná stránka, in-app widget a RSS nebo JSON feed jsou tři vykreslení jedné věci, a nikdo nic nepřepisuje cestou k zákazníkovi. E-mail s release notes může citovat stejný záznam, z jakéhokoli nástroje, kterým posíláte e-maily. Automatizace changelogu se týká toho, který z těchto kroků by měl vlastnit stroj. To je celý argument pro zacházení s changelogem jako s kanálem místo stránky. Je to také, s plnou transparentností, to, co budujeme, takže to čtěte jako zájem, ne nestranný průzkum.

Pokud máte čas jen na jedno

Pište changelog. Je levnější na záznam, užitečný v den, kdy ho napíšete, a release notes z něj lze později odvodit. Opak neplatí: nemůžete rekonstruovat rok změn z dvanácti oznamovacích e-mailů, a lidé vás o to požádají.

Udržujte ho v pevném formátu, aby odvození zůstalo možné. Naše stránka příklady changelogu shromažďuje záznamy od týmů, které to dělají dobře, a šablona release notes je forma, kterou používáme při proměně sady záznamů v něco, co stojí za odeslání.

Poznámka k pojmenování

Nic z toho není standardizováno, a najdete «release notes» používané pro průběžný seznam a «changelog» používaný pro čtvrtletní oznámení. Hádat se o slova se nevyplatí. Rozhodněte, kterou ze dvou prací plní každý z vašich artefaktů, pojmenujte ho tak, jak už ho nazývá váš tým, a ujistěte se, že žádný z nich tiše nedělá obojí.

Na jakém povrchu výsledek skončí, je samostatné rozhodnutí, probrané v jak postavit changelog stránku.

FAQ

Je changelog totéž co release notes? Ne. Changelog je úplný záznam, čtený těmi, kdo něco hledají; release notes jsou vybrané oznámení, čtené těmi, kdo se rozhodují, zda je to zajímá. Stejná změna se objevuje v obou, formulovaná jinak pro každého čtenáře.

Lze release notes vygenerovat z changelogu? Ano, a to je správný směr. Vyberte záznamy, na kterých by záleželo člověku, seskupte je podle výsledku, přepište titulek. Opak, rekonstrukce changelogu z oznámení, ztrácí vše, co oznámení vynechala.

Kde by měl changelog žít? Někde trvalém a odkazovatelném, kam se čtenář dostane bez repozitáře: na stránce /changelog, webu dokumentace, nebo kanálu vykreslovaném na více místech. Samotný CHANGELOG.md dosáhne na přispěvatele, ne na zákazníky.

Měl by changelog obsahovat interní změny? Ano, na konci, po jednom řádku každá. Changelog je úplný záznam. Release notes je mohou obsahovat také, v krátké poslední sekci, pokud změny, kterých si čtenář všimne, jsou na prvním místě.

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: Příklady changelogu, Šablona poznámek k vydání