Release notes k feature flagu: co napsat a kdy

Uzavření smyčky u požadavku na funkci předpokládá čistý moment, kdy byla věc vydána. Feature flag tento moment odstraňuje, a proto je u release notes k feature flagu tak těžké trefit načasování. Kód je sloučen, flag existuje, a dny nebo týdny poté je funkce zároveň živá v produkci a neviditelná pro skoro každého, kdo by ji chtěl použít, často včetně osoby, která o ni původně požádala. Informování příliš brzy ji přivede k funkci, která ještě není. Informování příliš pozdě způsobí, že smyčka, která měla budovat důvěru, se místo toho čte jako zapomenutá.

Proč flag rozbíjí obvyklou posloupnost „vydat, informovat”?

Protože rozděluje jednu událost na minimálně dvě: kód, který se stane živým, a flag, který se zapne pro konkrétní účet. Každý proces uzavírání smyčky zpětné vazby předpokládá, že tyto dvě věci se stanou spolu, což platí pro většinu vydání a neplatí pro cokoli za flagem používaným pro postupné vydávání, cílení nebo jako nouzový vypínač. Uzavírání smyčky zpětné vazby zákazníka popisuje informování žadatelky přesně v momentě, kdy je záznam changelogu schválen a zveřejněn; tento krok je napsaný pro případ, kdy zveřejnění záznamu a použitelnost funkce jsou stejný moment, a flag je přesně případ, kdy nejsou.

Jaké je skutečné pravidlo pro to, kdy někoho informovat?

Informuj, když je flag zapnutý pro její účet, ne když je kód sloučen a ne když je flag vytvořen. Toto jediné pravidlo pokrývá každý řádek tabulky výše, protože váže oznámení na jedinou skutečnost, na které žadatelce opravdu záleží: jestli může právě teď jít tu věc použít. Oznámení vázané na sloučení nebo vytvoření flagu je ve skutečnosti zpráva o inženýrském pokroku, a někdo, kdo požádal o funkci, nechce zprávu o pokroku, chce vědět, kdy se podívat.

Znamená to, že žadatelka potřebuje předčasný nebo speciální přístup?

Ne nutně, a vynucování toho vytváří vlastní problém. Pokud se flag vydává postupně z důvodů zátěže nebo stability, přesunutí jednoho účtu na začátek fronty jen proto, aby se smyčka uzavřela rychleji, podkopává důvod, proč je vydávání postupné. Poctivé možnosti jsou: počkat, až účet žadatelky přirozeně dosáhne vydávání, a informovat ji tehdy, nebo, pokud to naléhavost ospravedlní, záměrně jí flag zapnout dřív, jako skutečné rozhodnutí toho, kdo vydávání vlastní, ne jako vedlejší efekt touhy poslat oznámení.

Co když je flag nouzový vypínač, ne mechanismus vydávání?

Pak se bezpečný předpoklad obrátí. Flag zamýšlený k tomu, aby šlo funkci rychle vypnout, spíš než etapovat její vydání, obvykle znamená, že funkce má být plně živá hned po vytvoření, a flag existuje kvůli bezpečnosti, ne kvůli sekvenci. V takovém případě je informování žadatelky v momentě nasazení správné, stejně jako u jakéhokoli vydání bez flagu; existence flagu je provozní detail, který by neměl měnit, kdy se smyčka uzavírá. Rozlišení, na kterém záleží, je k čemu flag slouží, ne jestli nějaký existuje.

Mění flag to, co mají říkat release notes k feature flagu?

Mění, kdy je záznam zveřejněn, ne co obsahuje. Záznam zveřejněný přesně v momentě, kdy je flag zapnutý pro 100 % účtů, se čte přesně jako normální záznam changelogu, a to je správně; čtenářka, která ho najde později, nemá důvod vědět, že v tom někdy flag byl. Co by dělat neměl, je být zveřejněn, zatímco flag je zapnutý jen pro malé procento vydávání, protože veřejný záznam changelogu pošle každého, kdo ho čte, včetně účtů bez flagu, hledat funkci, kterou nenajdou, což je horší verze stejného problému, v měřítku celého produktu místo měřítka jedné žadatelky. Tohle pravidlo o načasování je celý rozdíl mezi release notes k feature flagu a běžným záznamem: obsah je stejný, mění se jen datum zveřejnění. Jak psát release notes rozebírá disciplínu „žádná akce není nutná”, která platí i tady: čtenářky musí vědět, jestli se jich to týká, ne jen že to někde existuje.

Měly by e-maily o aktualizaci produktu zacházet s funkcí za flagem jinak?

Ano, hlavně odkládáním místo přepisováním. Šablona e-mailu o aktualizaci produktu rozebírá cílená oznámení proti širokým digestům; funkce za flagem je případ, kdy se musí timing cíleného oznámení ověřit proti vlastnímu stavu flagu příjemkyně před odesláním, což široký digest vůbec nedokáže snadno udělat, což je další důvod, proč je digest špatný kanál pro cokoli, co je ještě uprostřed vydávání.

FAQ

Mělo by se žadatelce říct, že její funkce „brzy přijde”, jakmile flag existuje, ale ještě pro ni není zapnutý? Jen pokud je k tomu připojené skutečné, blízké datum, a i tak střídmě. „Brzy” bez data se po dostatečné době čte přesně jako mlčení a vytváří druhý slib, který se taky musí sledovat a dodržet.

Kdo rozhoduje, kdy je flag dost daleko na to, aby se smyčka uzavřela? Kdokoli vlastní vydávání, ne kdokoli vlastní oznámení. Vlastník vydávání ví, jestli je „100 % účtů” blízko, nebo ještě týdny daleko; navázání kroku uzavření smyčky na jeho stav, místo na pevné kalendářní datum, udržuje oznámení poctivé.

Dostane funkce za trvalým flagem (nikdy úplně neodstraněným) někdy veřejný záznam changelogu? Ano, jakmile dosáhne toho, co pro ten produkt znamená „obecná dostupnost”, i když samotný flag zůstane v kódu navždy z provozních důvodů. Záznam changelogu je o dostupnosti pro čtenářku, ne o implementačním detailu, jak je ta dostupnost realizovaná.

Co když je flag odstraněn a funkce zabita místo vydána? To je odmítnutí, ne oznámení o vydání, a zaslouží si stejnou péči jako jakékoli jiné odmítnutí. Jak odmítnout požadavek na funkci rozebírá, co by ta zpráva měla říkat; poctivé uzavření smyčky někdy znamená uzavřít ji ne.

Potřebují release notes k feature flagu jinou šablonu než běžný záznam? Žádná změna šablony, jen jeden kontrolní krok před zveřejněním: ověřit stav flagu pro účet, který žádal, ne jen že se kód sloučil, a záznam zadržet, dokud tahle kontrola neprojde. Všechno ostatní na záznamu, formulace, délka, disciplína FAQ, zůstává stejné jako u jakéhokoli jiného release notes.

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: Dokumentace pro vývojáře, Srovnání nástrojů pro changelog