Release notes de feature flag: o que dizer, e quando
6 min de leitura
Fechar o ciclo em um pedido de funcionalidade assume um momento limpo em que a coisa foi lançada. Um feature flag remove esse momento, e é isso que torna difícil acertar a hora das release notes de feature flag. O código é mergeado, o flag existe, e por dias ou semanas depois disso a funcionalidade está ao mesmo tempo viva em produção e invisível para quase todo mundo que poderia querer usá-la, muitas vezes incluindo a pessoa que pediu originalmente. Avisar cedo demais faz essa pessoa esbarrar em uma funcionalidade que ainda não existe. Avisar tarde demais faz o ciclo que deveria construir confiança soar, em vez disso, como esquecido.
Por que um flag quebra a sequência usual de “lançar, avisar”?
Porque ele divide um evento em pelo menos dois: o código se tornando ativo, e o flag sendo ligado para uma conta específica. Todo processo de fechar um ciclo de feedback assume que esses dois acontecem juntos, o que é verdade para a maioria dos lançamentos e falso para tudo que está atrás de um flag usado para lançamento gradual, segmentação ou como interruptor de emergência. Fechando o ciclo de feedback do cliente descreve avisar quem pediu bem no momento em que uma entrada de changelog é aprovada e publicada; esse passo é escrito para o caso em que publicar a entrada e a funcionalidade ficar utilizável são o mesmo momento, e um flag é exatamente o caso em que não são.
| Momento | O que é verdade | Já deveria avisar quem pediu |
|---|---|---|
| Código mergeado, flag desligado em todo lugar | A funcionalidade existe, ninguém pode usá-la | Não |
| Flag ligado para a conta de quem pediu | A funcionalidade existe, essa pessoa especificamente pode usá-la | Sim |
| Flag ligado para uma porcentagem de lançamento que a exclui | A funcionalidade existe, essa pessoa ainda não pode usá-la | Não |
| Flag totalmente removido, funcionalidade simplesmente está ligada | A funcionalidade existe para todo mundo | Sim, se ainda não avisou |
Qual é a regra real para quando avisar alguém?
Avise quando o flag estiver ligado para a conta dela, não quando o código for mergeado e não quando o flag for criado. Essa única regra cobre cada linha da tabela acima, porque liga o aviso ao único fato que realmente importa para quem pediu: se ela pode, agora mesmo, ir usar a coisa. Um aviso ligado ao merge ou à criação do flag é na verdade um relatório de progresso de engenharia, e quem pediu uma funcionalidade não quer um relatório de progresso, quer saber quando ir olhar.
Isso significa que quem pediu precisa de acesso antecipado ou especial?
Não necessariamente, e forçar isso cria seu próprio problema. Se o flag está sendo lançado gradualmente por motivos de carga ou estabilidade, mover uma conta para a frente da fila só para fechar um ciclo mais rápido mina o motivo pelo qual o lançamento é escalonado em primeiro lugar. As opções honestas são: esperar a conta de quem pediu chegar naturalmente ao lançamento e avisar então, ou, se a urgência justificar, ligar o flag deliberadamente mais cedo para ela, como uma decisão real de quem for dono do lançamento, não como efeito colateral da vontade de mandar um aviso.
E se o flag for um interruptor de emergência, não um mecanismo de lançamento?
Aí a suposição segura se inverte. Um flag pensado para poder desligar rapidamente uma funcionalidade, em vez de escalonar seu lançamento, geralmente significa que a funcionalidade deveria estar totalmente ativa no momento em que é criada, e o flag existe por segurança, não por sequência. Nesse caso, avisar quem pediu no momento do deploy está correto, igual a qualquer lançamento sem flag; a existência do flag é um detalhe operacional que não deveria mudar quando o ciclo fecha. A distinção que importa é para que o flag serve, não se um existe.
O flag muda o que as release notes de feature flag deveriam dizer?
Muda quando a entrada é publicada, não o que ela contém. Uma entrada publicada bem no momento em que o flag está ligado para 100% das contas se lê exatamente como uma entrada de changelog normal, e deve ser assim; uma leitora que a encontra depois não tem motivo para saber que um flag algum dia esteve envolvido. O que não deveria fazer é ser publicada enquanto o flag está ligado só para uma pequena porcentagem de lançamento, porque uma entrada pública de changelog manda todo mundo que a lê, incluindo contas sem o flag, procurar uma funcionalidade que não vão encontrar, o que é uma versão pior do mesmo problema, na escala do produto inteiro em vez da escala de quem pediu. Essa regra de timing é toda a diferença entre release notes de feature flag e uma entrada comum: o conteúdo é o mesmo, só a data de publicação muda. Como escrever release notes cobre a disciplina do “nenhuma ação necessária” que também se aplica aqui: leitoras precisam saber se isso as afeta, não só que existe em algum lugar.
E-mails de atualização de produto deveriam tratar uma funcionalidade com flag diferente?
Sim, principalmente adiando em vez de reescrevendo. O template de e-mail de atualização de produto cobre notificações direcionadas versus resumos amplos; uma funcionalidade com flag é um caso em que o timing de uma notificação direcionada precisa ser verificado contra o próprio estado do flag da destinatária antes de ser enviada, algo que um resumo amplo não consegue fazer facilmente de jeito nenhum, o que é mais um motivo pelo qual um resumo é o canal errado para qualquer coisa ainda no meio do lançamento.
FAQ
Deveria dizer a quem pediu que a funcionalidade dela “está chegando” assim que o flag existe mas ainda não está ligado para ela? Só se houver uma data real e próxima anexada, e mesmo assim com moderação. Um “está chegando” sem data se lê, depois de tempo suficiente, exatamente como silêncio, e cria uma segunda promessa que também precisa ser rastreada e cumprida.
Quem decide quando um flag está avançado o suficiente para fechar o ciclo? Quem for dono do lançamento, não quem for dono da notificação. Quem tem o lançamento sabe se “100% das contas” está iminente ou ainda a semanas de distância; ligar o passo de fechamento do ciclo ao estado dela, em vez de a uma data fixa no calendário, mantém o aviso honesto.
Uma funcionalidade atrás de um flag permanente (nunca totalmente removido) algum dia recebe uma entrada pública de changelog? Sim, assim que atinge o que quer que “disponibilidade geral” signifique para aquele produto, mesmo que o flag em si fique no código para sempre por motivos operacionais. A entrada de changelog é sobre disponibilidade para a leitora, não sobre o detalhe de implementação de como essa disponibilidade é realizada.
E se o flag for removido e a funcionalidade for morta em vez de lançada? Isso é uma recusa, não um aviso de lançamento, e merece o mesmo cuidado que qualquer outra recusa. Como recusar um pedido de funcionalidade cobre o que essa mensagem deveria dizer; fechar o ciclo com honestidade às vezes significa fechá-lo com um não.
Release notes de feature flag precisam de um template separado de uma entrada normal? Nenhuma mudança de template, só um passo de verificação antes de publicar: checar o estado do flag para a conta de quem pediu, não só que o código foi mergeado, e segurar a entrada até essa checagem passar. Tudo mais na entrada, a formulação, o tamanho, a disciplina de FAQ, continua igual a qualquer outra release note.
As afirmações técnicas deste artigo não foram revisadas de forma independente. Se algo estiver errado, avise a gente e vamos corrigir.