Release notes per i feature flag: cosa dire, e quando
6 min di lettura
Chiudere il ciclo su una richiesta di funzionalità presuppone un momento netto in cui la cosa è stata rilasciata. Un feature flag elimina quel momento, ed è per questo che scegliere quando pubblicare le release notes per i feature flag è difficile. Il codice viene mergiato, il flag esiste, e per giorni o settimane dopo la funzionalità è contemporaneamente live in produzione e invisibile per quasi chiunque potrebbe volerla usare, spesso inclusa la persona che l’aveva richiesta in origine. Avvisare troppo presto la fa imbattere in una funzionalità che ancora non c’è. Avvisare troppo tardi fa sì che il ciclo che doveva costruire fiducia si legga, invece, come dimenticato.
Perché un flag rompe la solita sequenza “rilascialo, avvisa”?
Perché divide un evento in almeno due: il codice che diventa live, e il flag che viene attivato per un account specifico. Ogni processo per chiudere un ciclo di feedback presuppone che questi accadano insieme, il che è vero per la maggior parte dei rilasci e falso per qualsiasi cosa dietro a un flag usato per rollout graduale, targeting o come interruttore di emergenza. Chiudere il ciclo di feedback del cliente descrive l’avvisare chi ha fatto la richiesta nel momento esatto in cui una voce di changelog viene approvata e pubblicata; quel passaggio è scritto per il caso in cui pubblicare la voce e l’usabilità della funzionalità siano lo stesso momento, e un flag è esattamente il caso in cui non lo sono.
| Momento | Cosa è vero | Bisogna già avvisare chi ha fatto la richiesta |
|---|---|---|
| Codice mergiato, flag spento ovunque | La funzionalità esiste, nessuno può usarla | No |
| Flag acceso per l’account di chi ha richiesto | La funzionalità esiste, quella persona specifica può usarla | Sì |
| Flag acceso per una percentuale di rollout che la esclude | La funzionalità esiste, quella persona ancora non può usarla | No |
| Flag rimosso del tutto, la funzionalità è semplicemente attiva | La funzionalità esiste per tutti | Sì, se non già avvisato |
Qual è la regola vera per sapere quando avvisare qualcuno?
Avvisa quando il flag è acceso per il suo account, non quando il codice viene mergiato e non quando il flag viene creato. Questa singola regola copre ogni riga della tabella sopra, perché lega l’avviso all’unico fatto che conta davvero per chi ha fatto la richiesta: se può, proprio adesso, andare a usare la cosa. Un avviso legato al merge o alla creazione del flag è in realtà un resoconto di avanzamento ingegneristico, e chi ha richiesto una funzionalità non vuole un resoconto di avanzamento, vuole sapere quando andare a guardare.
Questo significa che chi ha fatto la richiesta ha bisogno di accesso anticipato o speciale?
Non necessariamente, e forzarlo crea un problema tutto suo. Se il flag viene rilasciato gradualmente per motivi di carico o stabilità, spostare un account in cima alla coda solo per chiudere un ciclo più velocemente mina la ragione per cui il rollout è scaglionato in primo luogo. Le opzioni oneste sono: aspettare che l’account di chi ha fatto la richiesta raggiunga il rollout naturalmente e avvisarlo allora, oppure, se l’urgenza lo giustifica, attivargli deliberatamente il flag in anticipo, come una decisione reale di chi possiede il rollout, non come effetto collaterale del voler mandare una notifica.
E se il flag è un interruttore di emergenza, non un meccanismo di rollout?
Allora l’assunzione sicura si capovolge. Un flag pensato per poter disattivare rapidamente una funzionalità, piuttosto che scaglionarne il rilascio, di solito significa che la funzionalità è pensata per essere completamente live appena viene creato, e il flag esiste per sicurezza piuttosto che per sequenza. In quel caso, avvisare chi ha fatto la richiesta al momento del deploy è corretto, come per qualsiasi rilascio senza flag; la presenza del flag è un dettaglio operativo che non dovrebbe cambiare quando il ciclo si chiude. La distinzione che conta è a cosa serve il flag, non se ne esiste uno.
Il flag cambia cosa dovrebbero dire le release notes per il feature flag?
Cambia quando la voce viene pubblicata, non cosa contiene. Una voce pubblicata nel momento esatto in cui il flag è acceso per il 100% degli account si legge esattamente come una normale voce di changelog, ed è giusto così; chi la trova più tardi non ha motivo di sapere che un flag sia mai stato coinvolto. Quello che non dovrebbe fare è essere pubblicata mentre il flag è acceso solo per una piccola percentuale di rollout, perché una voce pubblica di changelog manda chiunque la legga, inclusi gli account senza il flag, a cercare una funzionalità che non troveranno, il che è una versione peggiore dello stesso problema, su scala di tutto il prodotto invece che sulla scala di chi ha fatto la richiesta. Quella regola sul tempismo è tutta la differenza tra le release notes per un feature flag e una voce ordinaria: il contenuto è lo stesso, cambia solo la data di pubblicazione. Come scrivere release notes copre la disciplina del “nessuna azione necessaria” che si applica anche qui: chi legge deve sapere se questo lo riguarda, non solo che esiste da qualche parte.
Le email di aggiornamento prodotto dovrebbero trattare diversamente una funzionalità con flag?
Sì, soprattutto ritardandola invece di riscriverla. Il template dell’email di aggiornamento prodotto copre le notifiche mirate contro i digest ampi; una funzionalità con flag è un caso in cui il tempismo di una notifica mirata va verificato contro lo stato del flag della destinataria prima di essere inviata, cosa che un digest ampio non può fare facilmente affatto, il che è un motivo in più per cui un digest è il canale sbagliato per qualsiasi cosa ancora a metà rollout.
FAQ
Bisogna dire a chi ha fatto la richiesta che la sua funzionalità “arriverà presto” quando il flag esiste ma non è ancora acceso per lei? Solo se c’è una data reale e vicina, e anche allora con parsimonia. Un “presto” senza data si legge, passato abbastanza tempo, esattamente come il silenzio, e crea una seconda promessa che va anche lei tracciata e mantenuta.
Chi decide quando un flag è abbastanza avanti da chiudere il ciclo? Chi possiede il rollout, non chi possiede la notifica. Chi ha il rollout sa se il “100% degli account” è imminente o ancora a settimane di distanza; legare il passaggio di chiusura del ciclo al suo stato, invece che a una data fissa, mantiene onesto l’avviso.
Una funzionalità dietro un flag permanente (mai rimosso del tutto) riceve mai una voce pubblica di changelog? Sì, appena raggiunge qualunque cosa significhi “disponibilità generale” per quel prodotto, anche se il flag stesso resta nel codice per sempre per ragioni operative. La voce di changelog riguarda la disponibilità per chi legge, non il dettaglio implementativo di come quella disponibilità è realizzata.
E se il flag viene rimosso e la funzionalità viene eliminata invece di essere rilasciata? Quello è un rifiuto, non un avviso di rilascio, e merita la stessa cura di qualsiasi altro rifiuto. Come rifiutare una richiesta di funzionalità copre cosa dovrebbe dire quel messaggio; chiudere il ciclo onestamente a volte significa chiuderlo con un no.
Le release notes per un feature flag hanno bisogno di un template separato da una voce normale? Nessun cambio di template, solo un passaggio di controllo prima della pubblicazione: verificare lo stato del flag per l’account che ha fatto la richiesta, non solo che il codice sia stato mergiato, e trattenere la voce finché quel controllo non passa. Tutto il resto della voce, la formulazione, la lunghezza, la disciplina delle FAQ, resta uguale a qualsiasi altra release note.
Le affermazioni tecniche di questo articolo non sono state verificate in modo indipendente. Se qualcosa non è corretto, faccelo sapere e lo correggeremo.