Release notes dla feature flagów: co i kiedy napisać

Zamknięcie pętli przy prośbie o funkcję zakłada wyraźny moment, w którym coś zostało wydane. Feature flag usuwa ten moment i właśnie dlatego trudno wyczuć, kiedy publikować release notes dla feature flagów. Kod jest mergowany, flaga istnieje, a przez dni albo tygodnie potem funkcja jest jednocześnie żywa na produkcji i niewidoczna dla prawie każdego, kto mógłby chcieć jej użyć, często włącznie z osobą, która pierwotnie o nią poprosiła. Poinformowanie zbyt wcześnie sprawia, że trafia ona na funkcję, której jeszcze nie ma. Poinformowanie zbyt późno sprawia, że pętla, która miała budować zaufanie, zamiast tego czyta się jako zapomniana.

Dlaczego flaga psuje zwykłą kolejność “wydaj, poinformuj”?

Bo dzieli jedno wydarzenie na co najmniej dwa: kod stający się żywy, i flagę włączaną dla danego konta. Każdy proces zamykania pętli feedbacku zakłada, że te dwie rzeczy dzieją się razem, co jest prawdą dla większości wydań i nieprawdą dla wszystkiego za flagą używaną do stopniowego wdrażania, targetowania albo jako wyłącznik awaryjny. Zamykanie pętli feedbacku klienta opisuje informowanie proszącej dokładnie w momencie, gdy wpis w changelogu zostaje zatwierdzony i opublikowany; ten krok jest napisany dla przypadku, w którym publikacja wpisu i użyteczność funkcji to ten sam moment, a flaga to dokładnie przypadek, w którym nie są.

Jaka jest prawdziwa zasada, kiedy kogoś informować?

Informuj, gdy flaga jest włączona dla jej konta, nie gdy kod jest mergowany i nie gdy flaga jest tworzona. Ta jedna zasada obejmuje każdą linię tabeli powyżej, bo wiąże powiadomienie z jedynym faktem, który naprawdę liczy się dla proszącej: czy może, właśnie teraz, pójść i użyć tej rzeczy. Powiadomienie związane z mergem albo utworzeniem flagi jest w rzeczywistości raportem o postępach inżynieryjnych, a osoba, która poprosiła o funkcję, nie chce raportu o postępach, chce wiedzieć, kiedy sprawdzić.

Czy to znaczy, że proszącej potrzebny jest wcześniejszy albo specjalny dostęp?

Niekoniecznie, a wymuszanie tego tworzy własny problem. Jeśli flaga jest wdrażana stopniowo z powodów obciążenia albo stabilności, przesunięcie jednego konta na początek kolejki tylko po to, by szybciej zamknąć pętlę, podważa powód, dla którego wdrożenie jest etapowe. Uczciwe opcje to: poczekać, aż konto proszącej naturalnie dotrze do wdrożenia i wtedy ją poinformować, albo, jeśli pilność to uzasadnia, celowo włączyć jej flagę wcześniej, jako prawdziwą decyzję kogokolwiek, kto jest właścicielem wdrożenia, nie jako efekt uboczny chęci wysłania powiadomienia.

A jeśli flaga jest wyłącznikiem awaryjnym, nie mechanizmem wdrożenia?

Wtedy bezpieczne założenie się odwraca. Flaga stworzona po to, by móc szybko wyłączyć funkcję, zamiast etapować jej wydanie, zwykle oznacza, że funkcja ma być w pełni żywa w chwili utworzenia, a flaga istnieje dla bezpieczeństwa, nie dla sekwencji. W takim przypadku poinformowanie proszącej w momencie wdrożenia jest poprawne, tak jak przy każdym wydaniu bez flagi; obecność flagi to operacyjny szczegół, który nie powinien zmieniać, kiedy pętla się zamyka. Rozróżnienie, które ma znaczenie, to do czego flaga służy, nie czy w ogóle istnieje.

Czy flaga zmienia, co powinny mówić release notes o feature flagu?

Zmienia, kiedy wpis jest publikowany, nie co zawiera. Wpis opublikowany dokładnie w momencie, gdy flaga jest włączona dla 100% kont, czyta się dokładnie jak zwykły wpis w changelogu, i tak powinno być; czytelniczka, która znajdzie go później, nie ma powodu wiedzieć, że kiedykolwiek brała w tym udział flaga. Czego nie powinien robić, to być publikowany, gdy flaga jest włączona tylko dla małego procentu wdrożenia, bo publiczny wpis w changelogu wysyła każdego, kto go czyta, w tym konta bez flagi, na poszukiwanie funkcji, której nie znajdą, co jest gorszą wersją tego samego problemu, w skali całego produktu zamiast skali jednej proszącej. Ta zasada timingu to cała różnica między release notes o feature flagu a zwykłym wpisem: treść jest ta sama, przesuwa się tylko data publikacji. Jak pisać release notes opisuje dyscyplinę “nie trzeba żadnego działania”, która obowiązuje też tutaj: czytelniczki muszą wiedzieć, czy to ich dotyczy, nie tylko, że gdzieś istnieje.

Czy e-maile o aktualizacji produktu powinny traktować funkcję z flagą inaczej?

Tak, głównie przez opóźnianie zamiast przepisywanie. Szablon e-maila o aktualizacji produktu opisuje ukierunkowane powiadomienia w porównaniu z szerokimi digestami; funkcja z flagą to przypadek, w którym timing ukierunkowanego powiadomienia trzeba sprawdzić względem własnego stanu flagi odbiorczyni, zanim zostanie wysłane, czego szeroki digest w ogóle nie potrafi łatwo zrobić, co jest kolejnym powodem, dla którego digest to zły kanał dla wszystkiego, co wciąż jest w połowie wdrożenia.

FAQ

Czy trzeba powiedzieć proszącej, że jej funkcja “wkrótce się pojawi”, gdy flaga istnieje, ale nie jest jeszcze dla niej włączona? Tylko jeśli towarzyszy temu prawdziwa, bliska data, i nawet wtedy oszczędnie. “Wkrótce” bez daty czyta się, po wystarczającym czasie, dokładnie jak milczenie, i tworzy drugą obietnicę, którą też trzeba śledzić i dotrzymać.

Kto decyduje, kiedy flaga jest wystarczająco zaawansowana, by zamknąć pętlę? Ktokolwiek jest właścicielem wdrożenia, nie ktokolwiek jest właścicielem powiadomienia. Właścicielka wdrożenia wie, czy “100% kont” jest bliskie, czy wciąż o tygodnie odległe; związanie kroku zamykania pętli z jej stanem, zamiast ze stałą datą w kalendarzu, utrzymuje powiadomienie uczciwym.

Czy funkcja za trwałą flagą (nigdy w pełni nieusuniętą) kiedykolwiek dostaje publiczny wpis w changelogu? Tak, gdy osiąga to, co dla tego produktu oznacza “ogólna dostępność”, nawet jeśli sama flaga zostaje w kodzie na zawsze z powodów operacyjnych. Wpis w changelogu dotyczy dostępności dla czytelniczki, nie szczegółu implementacyjnego, jak ta dostępność jest realizowana.

A jeśli flaga zostaje usunięta, a funkcja zabita zamiast wydana? To jest odmowa, nie powiadomienie o wydaniu, i zasługuje na taką samą staranność jak każda inna odmowa. Jak odrzucić prośbę o funkcję opisuje, co powinna mówić taka wiadomość; uczciwe zamknięcie pętli czasem oznacza zamknięcie jej odmową.

Czy release notes o feature flagu potrzebują osobnego szablonu niż zwykły wpis? Bez zmiany szablonu, tylko krok bramkujący przed publikacją: sprawdźcie stan flagi dla konta, które poprosiło, nie tylko to, że kod się zmergował, i wstrzymajcie wpis, dopóki ta kontrola nie przejdzie. Wszystko inne we wpisie, sformułowanie, długość, dyscyplina FAQ, pozostaje takie samo jak w każdych innych release notes.

Twierdzenia techniczne w tym artykule nie zostały niezależnie zweryfikowane. Jeśli coś się nie zgadza, daj nam znać, a poprawimy to.

Powiązane w changeloop: Dokumentacja dla deweloperów, Porównanie narzędzi do changeloga