Feature flag release notes: wat je zegt, en wanneer

De loop sluiten op een featureverzoek veronderstelt een duidelijk moment waarop het ding werd uitgebracht. Een feature flag haalt dat moment weg, en precies daardoor is de timing van feature flag release notes lastig. De code wordt gemerged, de flag bestaat, en dagen of weken daarna is de feature tegelijk live in productie en onzichtbaar voor bijna iedereen die hem zou willen gebruiken, vaak inclusief degene die er oorspronkelijk om vroeg. Te vroeg inlichten laat iemand tegen een feature aanlopen die er nog niet is. Te laat inlichten zorgt ervoor dat de loop die vertrouwen zou moeten opbouwen in plaats daarvan overkomt als vergeten.

Waarom breekt een flag de gebruikelijke volgorde “uitbrengen, inlichten”?

Omdat het één gebeurtenis splitst in minstens twee: de code die live gaat, en de flag die wordt aangezet voor een bepaald account. Elk proces om een feedbackloop te sluiten veronderstelt dat die twee samen gebeuren, wat waar is voor de meeste releases en onwaar voor alles achter een flag die gebruikt wordt voor gefaseerde uitrol, targeting of als noodschakelaar. De klant-feedbackloop sluiten beschrijft het inlichten van de aanvrager op het precieze moment dat een changelog-entry wordt goedgekeurd en gepubliceerd; die stap is geschreven voor het geval waarin het publiceren van de entry en de feature bruikbaar worden hetzelfde moment zijn, en een flag is precies het geval waarin dat niet zo is.

Wat is de echte regel voor wanneer je iemand inlicht?

Licht in wanneer de flag aan staat voor hun account, niet wanneer de code wordt gemerged en niet wanneer de flag wordt aangemaakt. Die ene regel dekt elke rij in de tabel hierboven, omdat hij de melding koppelt aan het enige feit dat er voor de aanvrager echt toe doet: kan hij, op dit moment, het ding gaan gebruiken. Een melding gekoppeld aan de merge of het aanmaken van de flag is eigenlijk een voortgangsrapport over engineering, en wie een feature aanvroeg wil geen voortgangsrapport, die wil weten wanneer te gaan kijken.

Betekent dat dat de aanvrager vroege of speciale toegang nodig heeft?

Niet per se, en het afdwingen creëert zijn eigen probleem. Als de flag geleidelijk wordt uitgerold om redenen van belasting of stabiliteit, ondermijnt het vooraan de wachtrij zetten van één account alleen om een loop sneller te sluiten de reden waarom de uitrol gefaseerd is. De eerlijke opties zijn: wachten tot het account van de aanvrager de uitrol op natuurlijke wijze bereikt en dan inlichten, of, als de urgentie het rechtvaardigt, hen bewust vroeg de flag geven, als een echte beslissing van wie de uitrol bezit, niet als bijeffect van de wens een melding te versturen.

Wat als de flag een noodschakelaar is, geen uitrolmechanisme?

Dan draait de veilige aanname om. Een flag bedoeld om een feature snel te kunnen uitschakelen, in plaats van de release ervan te faseren, betekent meestal dat de feature volledig live hoort te zijn zodra hij wordt aangemaakt, en de flag bestaat voor veiligheid in plaats van volgorde. In dat geval is de aanvrager inlichten op het moment van deploy correct, net als bij elke release zonder flag; het bestaan van de flag is een operationeel detail dat niet zou moeten veranderen wanneer de loop sluit. Het onderscheid dat ertoe doet is waarvoor de flag dient, niet of er een bestaat.

Verandert de flag wat feature flag release notes zouden moeten zeggen?

Het verandert wanneer de entry wordt gepubliceerd, niet wat hij bevat. Een entry gepubliceerd op het precieze moment dat de flag aan staat voor 100% van de accounts, leest exact als een normale changelog-entry, en dat hoort ook zo; een lezer die hem later vindt heeft geen reden om te weten dat er ooit een flag bij betrokken was. Wat het niet zou moeten doen, is publiceren terwijl de flag slechts aan staat voor een klein uitrolpercentage, omdat een publieke changelog-entry iedereen die hem leest, inclusief accounts zonder de flag, op zoek stuurt naar een feature die ze niet zullen vinden, wat een ergere versie van hetzelfde probleem is, op productbrede schaal in plaats van op de schaal van één aanvrager. Die timingregel is het hele verschil tussen feature flag release notes en een gewone entry: de inhoud is hetzelfde, alleen de publicatiedatum verschuift. Release notes schrijven behandelt de discipline van “geen actie nodig” die ook hier geldt: lezers moeten weten of dit hen betreft, niet alleen dat het ergens bestaat.

Zouden product-update-e-mails een geflagde feature anders moeten behandelen?

Ja, vooral door uit te stellen in plaats van te herschrijven. De product-update-e-mailtemplate behandelt gerichte notificaties tegenover brede digests; een geflagde feature is een geval waarin de timing van een gerichte notificatie gecontroleerd moet worden tegen de eigen flagstatus van de ontvanger voordat hij verstuurd wordt, iets wat een brede digest helemaal niet gemakkelijk kan, wat nog een reden is waarom een digest het verkeerde kanaal is voor alles dat nog midden in de uitrol zit.

FAQ

Moet je een aanvrager vertellen dat hun feature “eraan komt” zodra de flag bestaat maar nog niet aan staat voor hen? Alleen als er een echte, nabije datum aan vasthangt, en zelfs dan spaarzaam. Een “eraan komt” zonder datum leest, na genoeg tijd, hetzelfde als stilte, en creëert een tweede belofte die ook bijgehouden en nagekomen moet worden.

Wie beslist wanneer een flag ver genoeg staat om de loop te sluiten? Wie de uitrol bezit, niet wie de notificatie bezit. Wie de uitrol heeft weet of “100% van de accounts” nabij is of nog weken weg; de sluitstap koppelen aan hun status, in plaats van aan een vaste kalenderdatum, houdt de melding eerlijk.

Krijgt een feature achter een permanente flag (nooit helemaal verwijderd) ooit een publieke changelog-entry? Ja, zodra hij bereikt wat “algemeen beschikbaar” ook betekent voor dat product, zelfs als de flag zelf om operationele redenen voor altijd in de code blijft. De changelog-entry gaat over beschikbaarheid voor de lezer, niet over het implementatiedetail van hoe die beschikbaarheid tot stand komt.

Wat als de flag verwijderd wordt en de feature gedood wordt in plaats van uitgebracht? Dat is een afwijzing, geen uitbrengmelding, en verdient dezelfde zorg als elke andere afwijzing. Hoe je een featureverzoek afwijst behandelt wat dat bericht zou moeten zeggen; de loop eerlijk sluiten betekent soms hem sluiten met een nee.

Hebben feature flag release notes een apart template nodig ten opzichte van een gewone entry? Geen templatewijziging, alleen een controlestap vóór publicatie: check de flagstatus voor het account dat vroeg, niet alleen dat de code is gemerged, en houd de entry vast tot die check slaagt. Al het andere aan de entry, de formulering, de lengte, de FAQ-discipline, blijft hetzelfde als bij elke andere release note.

De technische beweringen in dit artikel zijn niet onafhankelijk gecontroleerd. Klopt er iets niet, laat het ons weten, dan corrigeren we het.

Meer op changeloop: Documentatie voor ontwikkelaars, Changelog-tools vergeleken