Release notes k opravám chyb: jak psát použitelné záznamy

Dobré release notes k opravám chyb popisují, co uživatel viděl jít špatně, ne co udělal špatně kód. Každý záznam říká, koho se to týkalo, od kdy, zda je oprava úplná a zda čtenář musí něco udělat, i kdyby to bylo jen «není potřeba nic dělat».

Většina týmů zkopíruje řádek ze zprávy commitu. Tabulka ukazuje šest přepisů a sekce za ní vysvětlují pravidla.

Jak napsat záznam o opravě chyby v release notes?

Začněte příznakem slovy uživatele, pak koho se to týkalo a od kdy, potom stavem opravy a nakonec akcí. Obvykle stačí jedna nebo dvě věty. Příčina v kódu patří do pull requestu, kde ji bude hledat inženýr.

Čtenář hledá jedinou věc: «byl jsem to já?» Téměř každý záznam pokryjí čtyři části:

1. Příznak. Co se objevilo na obrazovce, v odpovědi API nebo na faktuře. Pokud byl chybový text, citujte ho, protože ho lidé vyhledávají.
2. Rozsah. Který tarif, platforma, verze API nebo tvar dat. «Účty s více než 50 000 řádky» se dá ověřit. «Někteří uživatelé» ne.
3. Období. Od kterého vydání nebo data, aby čtenář mohl posoudit, zda včerejší divný výsledek byla ta chyba.
4. Akce. Spustit znovu, znovu synchronizovat, aktualizovat, odstranit obejití, nebo vůbec nic.

Pokud si uživatelé postavili obejití, řádek akce je místo, kde jim řeknete, že ho mohou smazat.

Jaký je rozdíl mezi release note a changelogem?

Changelog je úplný průběžný záznam změn. Release notes jsou vybraná, přepsaná zpráva o jednom vydání pro lidi, kteří se rozhodují, zda je to zajímá. U oprav chyb changelog uvádí každou opravu a release notes začínají těmi, kterých si čtenář mohl všimnout.

Překlep v tooltipu patří jen do changelogu. Špatná sazba daně na fakturách patří do obou. Úplné rozdělení je v článku changelog vs release notes a tvar dobrého souboru poznámek v článku jak psát release notes.

Keep a Changelog je praktická konvence pro stranu záznamu. Pro opravy chyb si nechává sekci «Fixed» a pro zranitelnosti samostatný nadpis «Security», což je totéž rozdělení, jaké tento článek dělá pro čtenáře.

Je oprava chyby aktualizace?

Ano. Oprava chyby mění produkt, takže její vydání je aktualizace. Podle sémantického verzování je zpětně kompatibilní oprava patch vydání, například z 4.2.0 na 4.2.1.

Zda musí čtenář něco udělat, je samostatná otázka a poznámka by na ni měla odpovědět. Oprava, která mění to, co pozoruje správně volající kód, je blízko zásadní změně a breaking changes vysvětluje, kde ta hranice leží.

Kdy má oprava vlastní záznam a kdy je drobná?

Dejte opravě vlastní záznam, když si uživatel mohl chyby všimnout, přišel kvůli ní o čas nebo data, nebo kolem ní postavil obejití. Seskupte ji pod krátký seznam «Drobné opravy», když ji nikdo mimo váš tým nemohl vidět. Posuzujte ji podle zkušenosti čtenáře, ne podle velikosti diffu.

Každý řádek ve skupině by měl i tak něco říkat: «Opraveny některé problémy UI» je zástupný text.

Jak psát o regresi?

Pojmenujte vydání, které ji zavedlo, nazvěte ji regresí a uveďte vydání, které ji opravuje. Lidé, kteří na chybu narazili, už vědí, že se to rozbilo, takže jim krátké přímé přiznání poslouží lépe než vágní formulace.

Například: «Výsledky vyhledávání pro dotazy obsahující pomlčku se ve verzi 4.1.0 vracely prázdné. Ve verzi 4.1.1 je to opraveno. Pokud jste dotazy upravili, abyste se pomlčkám vyhnuli, můžete je vrátit zpět.»

«Vylepšena spolehlivost vyhledávání» působí jako vyhýbání každému, kdo kvůli chybě ztratil odpoledne. Pokud se příčina stále potvrzuje, řekněte to, jak to formuluje návod k pohotovostním release notes: nikdy nenechte poznámku znít jistěji, než je tým.

Jak oznámit bezpečnostní opravu?

Uveďte závažnost přímo, jmenujte dotčené verze a verzi, která je opravuje, řekněte, jak naléhavá je aktualizace, a přidejte identifikátor CVE, pokud existuje. Podrobnosti zveřejněte teprve tehdy, když uživatelé mohou opravu použít, podle procesu koordinovaného zveřejnění, pokud byl zapojen nahlašovatel.

Pořadí je důležité: nahlašovatel vám to sdělí soukromě, vy opravu vydáte a veřejná poznámka vyjde, když se uživatelé mohou chránit. Proces koordinovaného zveřejňování zranitelností od CISA koordinuje hlášení, analýzu a veřejné zveřejnění zranitelností. Pravidla CVE Numbering Authority upravují, jak se záznamy CVE přidělují a zveřejňují, a na GitHubu vám bezpečnostní advisory repozitáře umožní navrhnout advisory soukromě a požádat o identifikátor.

Bezpečnostní záznam obvykle nese čtyři fakty:

• Co mohl útočník udělat, v jedné větě a bez proof of concept.
• Dotčené verze a verze, která je opravuje.
• Jak je to naléhavé: «aktualizujte dnes» nebo «aktualizujte při příštím vydání».
• Zda jste viděli zneužití a poděkování nahlašovateli, pokud souhlasil.

Kroky exploitu vynechte.

Co má poznámka říct o opravě ztráty dat?

Řekněte, jaká data byla dotčena, jak poznat, zda ta vaše ano, a zda je lze obnovit. «Není potřeba nic dělat» tu platí zřídka a první otázka čtenáře zní «jsou moje data pryč?».

Použitelný záznam uvádí podmínku, která data ztratila («smazání složky během běžící synchronizace»), období, kdy to bylo možné, způsob kontroly («otevřete Koš a hledejte položky z 3. až 9. září») a cestu k obnově. Pokud data obnovit nelze, řekněte to. Dotčené zákazníky kontaktujte i přímo, protože release note by neměla být jediné místo, kde se někdo dozví, že jeho data byla zasažena.

Proč je «Opravy chyb a vylepšení výkonu» špatná poznámka?

Nedává čtenáři nic, na co by mohl reagovat, a schovává opravy, na které někdo čekal. Zákazník, který nahlásil pád, nepozná, zda je opraven, a zákazník s obejitím nepozná, zda ho má odstranit.

Existují dvě poctivé alternativy. Pokud vydání nemá nic, čeho by si čtenář mohl všimnout, nepublikujte k němu žádné poznámky a nechte záznam v changelogu. Pokud opravy má, vypište je v termínech čtenáře:

Před:
  Opravy chyb a vylepšení výkonu.

Po:
  Opraveno: export CSV selhával u projektů bez štítků.
  Opraveno: tmavý režim skrýval kurzor v poli komentáře.
  Rychlejší: dashboard se otevře dřív u prostorů
  s více než 100 projekty.

Odkud se berou poznámky k opravám chyb?

Berou se z pull requestu, který chybu opravil, a z hlášení, které ji spustilo. Pokud slova nahlašovatele cestují s opravou, je polovina příznaku napsaná.

Požadavek na funkci nebo chyba vysvětluje, proč správné označení hlášení rozhoduje o tom, kdo ho vlastní. V Changeloop se chyba nahlášená přes widget stane issue na GitHubu se štítkem bug a záznam changelogu se navrhne ze sloučeného pull requestu a drží se, dokud ho člověk neschválí. Šablona release notes vám dává stejný tvar záznamu pro ruční psaní: příznak, rozsah, období, akce.

FAQ

Co mají release notes k opravám chyb obsahovat? Každý záznam by měl uvést příznak, který uživatel viděl, koho se týkal, od kterého vydání nebo data, zda je oprava úplná a co má čtenář udělat, včetně «nic».

Má se každá oprava chyby uvádět v release notes? Ne. Uveďte ty, kterých si uživatel mohl všimnout, ztratil kvůli nim čas nebo je obcházel, a kosmetické či interní opravy seskupte pod krátký seznam «Drobné opravy». Changelog uchovává každou opravu pro každého, kdo ji potřebuje dohledat.

Jak napsat release notes k chybě, kterou jste sami zavedli? Řekněte, že šlo o regresi, jmenujte vydání, které ji zavedlo, a vydání, které ji opravuje, a sdělte čtenářům, zda mohou odstranit případné obejití. Prosté konstatování se čte lépe než změkčené formulace.

Jak najít release notes produktu, který používáte? Hledejte stránku s changelogem nebo release notes odkazovanou z nabídky nápovědy, patičky nebo dokumentace produktu, u open source projektů pak na kartě releases repozitáře.

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: Šablona poznámek k vydání