Feature flag: solte sem prender a respiração

spinny:~/writing $ vim openfeature-feature-flags-progressive-delivery.md

1~
2A implantação ocorre quando o código chega à produção. Liberação é quando alguém pode realmente usá-lo. Confundir os dois é uma das maneiras mais rápidas de tornar cada implantação um momento um pouco tenso.
3~
4Os feature flag servem para colocar espaço entre esses dois momentos. Você pode implantar hoje, iniciar amanhã para a equipe interna, depois para um cliente piloto e depois para 10% dos usuários. Se algo der errado, desligue a bandeira. Você não precisa necessariamente reverter a versão inteira.
5~
6## A bandeira não é apenas um if
7~
8Tecnicamente, geralmente é um `if`. Culturalmente é muito mais.
9~
10```typescript
11if (await flags.isEnabled('checkout.v2.enabled', context)) {
12  return newCheckout(input);
13}
14~
15return oldCheckout(input);
16```
17~
18Esse pequeno `if` pode representar uma implementação gradual, um experimento, uma migração, uma licença empresarial ou um kill switch operacional. O problema é que se você não administrar bem, também pode virar uma dívida técnica que fica no código por dois anos.
19~
20## Onde entra OpenFeature
21~
22OpenFeature é uma especificação aberta para avaliar feature flag com um API comum. A ideia é simples: o código da sua aplicação não deve depender diretamente do fornecedor ou do sistema interno que você usa para flags.
23~
24O aplicativo pergunta:
25~
26```typescript
27const enabled = await client.getBooleanValue('checkout.v2.enabled', false, {
28  targetingKey: user.id,
29  plan: user.plan,
30  country: user.country,
31});
32```
33~
34O provedor decide de onde vêm as regras: SaaS, arquivo, serviço interno, sinalizador, configuração do GitOps. Se um dia você alterar o back-end de sinalização de recursos, o aplicativo não precisará ser reescrito em todos os lugares.
35~
36Esta separação parece um detalhe arquitetônico, mas é sentida à medida que o projeto cresce.
37~
38## Contexto é metade da batalha
39~
40Um sinalizador ligado ou desligado para todos é útil, mas limitado. A entrega progressiva vive no contexto:
41~
42- usuário interno ou externo;
43- plano gratuito ou empresarial;
44- aldeia;
45- organização;
46- versão do aplicativo;
47- porcentagem estável de tráfego.
48~
49A chave importante é `targetingKey`: deve ser estável. Se mudar a cada solicitação, um usuário pode acabar uma vez na variante A e uma vez na variante B. Para um experimento é terrível, para um checkout pode ser desastroso.
50~
51## Uma implementação sensata
52~
53Um fluxo que gosto é este:
54~
551. implantar com sinalizador desativado;
562. ignição para desenvolvedores e controle de qualidade;
573. ativação para um cliente ou inquilino piloto;
584. Implementação de 5%;
595. implantação em 25%;
606. Implementação 100%;
617. remoção de código e sinalizador antigos.
62~
63O ponto frequentemente esquecido é o último. Uma bandeira temporária deve ter uma data de falecimento. Se permanecer para sempre, todo refatorador futuro terá que perguntar: "mas esse branch ainda é útil?".
64~
65## Kill switch: prepare-os primeiro
66~
67O kill switch é o sinalizador que salva você quando uma dependência externa começa a atrapalhar você, um trabalho consome muitos recursos ou uma nova lógica produz erros estranhos.
68~
69Um bom kill switch deve ser:
70~
71- fácil de encontrar;
72- documentado no runbook;
73- testado ocasionalmente;
74- observável quando ativado;
75- independente, tanto quanto possível, da parte que possa quebrar.
76~
77O pior é descobrir durante o acidente que a bandeira existe, mas ninguém sabe se ainda funciona.
78~
79## Observabilidade ou entrega não progressiva
80~
81Ativar um recurso em 10% sem olhar as métricas é apenas otimismo com múltiplas etapas.
82~
83Cada implementação deve responder a perguntas simples:
84~
85- os erros aumentaram?
86- a latência mudou?
87- os usuários completam o fluxo?
88- há mais tickets ou novas tentativas?
89- uma variante afeta apenas um segmento?
90~
91OpenFeature suporta ganchos em torno da avaliação de sinalizadores. Eles são úteis para registrar erros, adicionar métricas ou vincular a classificação a trace.
92~
93## Nomenclatura e propriedade
94~
95Os nomes são importantes. `new_ui` não diz nada. `checkout.v2.enabled` diz muito mais.
96~
97Para cada bandeira eu marcaria pelo menos:
98~
99- nome;
100- descrição;
101- proprietário;
102- padrão seguro;
103- razão pela qual existe;
104- data ou condição da remoção.
105~
106Uma bandeira sem dono é quase sempre uma bandeira que ninguém irá eliminar.
107~
108## Onde avaliá-los
109~
110Front-end, back-end ou edge? Depende.
111~
112Se o sinalizador for para layout, cópia ou integração, o frontend está bom. Se se tratar de permissões, cobrança, limites ou dados confidenciais, deve estar no backend. Se envolver roteamento ou experimentos de alto tráfego, a vantagem pode fazer sentido.
113~
114A regra simples: o frontend pode melhorar a experiência, mas não deve ser a única barreira de segurança.
115~
116## Conclusão
117~
118Os feature flag bem feitos mudam a relação com a produção. Eles não eliminam o risco, mas o tornam menor e mais gerenciável. Você pode soltar em fatias, observar, parar, voltar, aprender.
119~
120OpenFeature adiciona uma base limpa: um API comum, provedores intercambiáveis e uma maneira mais organizada de expandir o sistema. Mas a disciplina continua sendo sua: padrões seguros, nomes claros, métricas, proprietários e limpeza.
121~
122A melhor bandeira é aquela que te ajuda a liberar com calma e depois desaparece quando não for mais necessária.
123~
124## Fontes
125~
126- [OpenFeature: Introduction](https://openfeature.dev/docs/reference/intro/)
127- [OpenFeature: Node.js SDK](https://openfeature.dev/docs/reference/sdks/server/javascript/)
128- [OpenFeature Specification: Flag Evaluation API](https://openfeature.dev/specification/sections/flag-evaluation)
129- [OpenFeature: Hooks](https://openfeature.dev/docs/reference/concepts/hooks/)
130- [CNCF: OpenFeature](https://www.cncf.io/projects/openfeature/)
131~

NORMAL · openfeature-feature-flags-progressive-delivery.md [readonly]131 lines · :q to close

2A implantação ocorre quando o código chega à produção. Liberação é quando alguém pode realmente usá-lo. Confundir os dois é uma das maneiras mais rápidas de tornar cada implantação um momento um pouco tenso.

4Os feature flag servem para colocar espaço entre esses dois momentos. Você pode implantar hoje, iniciar amanhã para a equipe interna, depois para um cliente piloto e depois para 10% dos usuários. Se algo der errado, desligue a bandeira. Você não precisa necessariamente reverter a versão inteira.

6## A bandeira não é apenas um if

8Tecnicamente, geralmente é um `if`. Culturalmente é muito mais.

10```typescript

11if (await flags.isEnabled('checkout.v2.enabled', context)) {

12 return newCheckout(input);

13}

14~

15return oldCheckout(input);

16```

17~

18Esse pequeno `if` pode representar uma implementação gradual, um experimento, uma migração, uma licença empresarial ou um kill switch operacional. O problema é que se você não administrar bem, também pode virar uma dívida técnica que fica no código por dois anos.

19~

20## Onde entra OpenFeature

21~

22OpenFeature é uma especificação aberta para avaliar feature flag com um API comum. A ideia é simples: o código da sua aplicação não deve depender diretamente do fornecedor ou do sistema interno que você usa para flags.

23~

24O aplicativo pergunta:

25~

26```typescript

27const enabled = await client.getBooleanValue('checkout.v2.enabled', false, {

28 targetingKey: user.id,

29 plan: user.plan,

30 country: user.country,

31});

32```

33~

34O provedor decide de onde vêm as regras: SaaS, arquivo, serviço interno, sinalizador, configuração do GitOps. Se um dia você alterar o back-end de sinalização de recursos, o aplicativo não precisará ser reescrito em todos os lugares.

35~

36Esta separação parece um detalhe arquitetônico, mas é sentida à medida que o projeto cresce.

37~

38## Contexto é metade da batalha

39~

40Um sinalizador ligado ou desligado para todos é útil, mas limitado. A entrega progressiva vive no contexto:

41~

42- usuário interno ou externo;

43- plano gratuito ou empresarial;

44- aldeia;

45- organização;

46- versão do aplicativo;

47- porcentagem estável de tráfego.

48~

49A chave importante é `targetingKey`: deve ser estável. Se mudar a cada solicitação, um usuário pode acabar uma vez na variante A e uma vez na variante B. Para um experimento é terrível, para um checkout pode ser desastroso.

50~

51## Uma implementação sensata

52~

53Um fluxo que gosto é este:

54~

551. implantar com sinalizador desativado;

562. ignição para desenvolvedores e controle de qualidade;

573. ativação para um cliente ou inquilino piloto;

584. Implementação de 5%;

595. implantação em 25%;

606. Implementação 100%;

617. remoção de código e sinalizador antigos.

62~

63O ponto frequentemente esquecido é o último. Uma bandeira temporária deve ter uma data de falecimento. Se permanecer para sempre, todo refatorador futuro terá que perguntar: "mas esse branch ainda é útil?".

64~

65## Kill switch: prepare-os primeiro

66~

67O kill switch é o sinalizador que salva você quando uma dependência externa começa a atrapalhar você, um trabalho consome muitos recursos ou uma nova lógica produz erros estranhos.

68~

69Um bom kill switch deve ser:

70~

71- fácil de encontrar;

72- documentado no runbook;

73- testado ocasionalmente;

74- observável quando ativado;

75- independente, tanto quanto possível, da parte que possa quebrar.

76~

77O pior é descobrir durante o acidente que a bandeira existe, mas ninguém sabe se ainda funciona.

78~

79## Observabilidade ou entrega não progressiva

80~

81Ativar um recurso em 10% sem olhar as métricas é apenas otimismo com múltiplas etapas.

82~

83Cada implementação deve responder a perguntas simples:

84~

85- os erros aumentaram?

86- a latência mudou?

87- os usuários completam o fluxo?

88- há mais tickets ou novas tentativas?

89- uma variante afeta apenas um segmento?

90~

91OpenFeature suporta ganchos em torno da avaliação de sinalizadores. Eles são úteis para registrar erros, adicionar métricas ou vincular a classificação a trace.

92~

93## Nomenclatura e propriedade

94~

95Os nomes são importantes. `new_ui` não diz nada. `checkout.v2.enabled` diz muito mais.

96~

97Para cada bandeira eu marcaria pelo menos:

98~

99- nome;

100- descrição;

101- proprietário;

102- padrão seguro;

103- razão pela qual existe;

104- data ou condição da remoção.

105~

106Uma bandeira sem dono é quase sempre uma bandeira que ninguém irá eliminar.

107~

108## Onde avaliá-los

109~

110Front-end, back-end ou edge? Depende.

111~

112Se o sinalizador for para layout, cópia ou integração, o frontend está bom. Se se tratar de permissões, cobrança, limites ou dados confidenciais, deve estar no backend. Se envolver roteamento ou experimentos de alto tráfego, a vantagem pode fazer sentido.

113~

114A regra simples: o frontend pode melhorar a experiência, mas não deve ser a única barreira de segurança.

115~

116## Conclusão

117~

118Os feature flag bem feitos mudam a relação com a produção. Eles não eliminam o risco, mas o tornam menor e mais gerenciável. Você pode soltar em fatias, observar, parar, voltar, aprender.

119~

120OpenFeature adiciona uma base limpa: um API comum, provedores intercambiáveis e uma maneira mais organizada de expandir o sistema. Mas a disciplina continua sendo sua: padrões seguros, nomes claros, métricas, proprietários e limpeza.

121~

122A melhor bandeira é aquela que te ajuda a liberar com calma e depois desaparece quando não for mais necessária.

123~

124## Fontes

125~

126- [OpenFeature: Introduction](https://openfeature.dev/docs/reference/intro/)

127- [OpenFeature: Node.js SDK](https://openfeature.dev/docs/reference/sdks/server/javascript/)

128- [OpenFeature Specification: Flag Evaluation API](https://openfeature.dev/specification/sections/flag-evaluation)

129- [OpenFeature: Hooks](https://openfeature.dev/docs/reference/concepts/hooks/)

130- [CNCF: OpenFeature](https://www.cncf.io/projects/openfeature/)

131~