changeloop blog

Release notes de correção de bugs: entradas úteis

Fri, 02 Oct 2026 00:00:00 GMT

Boas release notes de correção de bugs descrevem o que o usuário viu dar errado, não o que o código fez de errado. Cada entrada diz quem foi afetado, desde quando, se a correção é completa e se o leitor precisa fazer alguma coisa, mesmo que seja apenas "nenhuma ação necessária".

A maioria das equipes copia uma linha da mensagem de commit. A tabela mostra seis reescritas, e as seções depois dela explicam as regras.

Antes (a mensagem de commit)	Depois (o sintoma)
Corrigido null pointer no handler de export	Exportações não falham mais com "Algo deu errado" quando um projeto não tem tags. Execute de novo qualquer exportação que falhou desde 3 de setembro.
Resolvida race condition no worker de sync	Edições feitas em dois dispositivos com poucos segundos de diferença não se sobrescrevem mais. Nada a fazer.
Corrigido bug de fuso horário	Relatórios agendados agora rodam no horário que você definiu. Contas a leste do UTC viam relatórios até um dia antes desde 12 de agosto. Nenhuma mudança necessária.
Corrigido XSS no renderizador de comentários	Correção de segurança: um comentário malicioso podia executar um script no navegador de outro usuário. Atualize para a 4.2.1 hoje. Não vimos exploração nos nossos logs.
Corrigida regressão da 4.1.0	A busca voltou a funcionar para consultas com hífen. Quebrou na 4.1.0 e está corrigida na 4.1.1.
Correções de bugs e melhorias de desempenho	Diga quais. Veja a última seção.

Como escrever uma entrada de correção de bug nas release notes?

Comece pelo sintoma nas palavras do usuário, depois quem foi afetado e desde quando, depois o estado da correção e por fim a ação. Uma ou duas frases costumam bastar. A causa no código pertence ao pull request, onde um engenheiro vai procurá-la.

O leitor procura uma coisa só: "era comigo?" Quatro partes cobrem quase toda entrada:

O sintoma. O que apareceu na tela, na resposta da API ou na fatura. Cite o texto do erro, se houve um, porque as pessoas o pesquisam.
O alcance. Qual plano, plataforma, versão de API ou formato de dados. "Contas com mais de 50.000 linhas" dá para conferir. "Alguns usuários" não.
A janela. Desde qual release ou data, para o leitor decidir se o resultado estranho de ontem era o bug.
A ação. Executar de novo, ressincronizar, atualizar, remover uma solução alternativa ou nada.

Se os usuários criaram uma solução alternativa, a linha de ação é onde vocês dizem que ela pode ser apagada.

Qual é a diferença entre uma release note e um changelog?

Um changelog é o registro completo e contínuo das mudanças. Release notes são uma mensagem selecionada e reescrita sobre uma release, para quem decide se deve se importar. Nas correções de bugs, o changelog lista todas e as notas abrem com as que um leitor poderia ter notado.

Um erro de digitação em um tooltip pertence só ao changelog. Uma alíquota de imposto errada nas faturas pertence aos dois. A divisão completa está em changelog vs release notes, e a forma de um bom conjunto de notas está em como escrever release notes.

Keep a Changelog é uma convenção prática para o lado do registro. Ela reserva "Fixed" para qualquer correção de bug e um título "Security" separado para vulnerabilidades, que é a mesma divisão que este artigo faz para o leitor.

Uma correção de bug é uma atualização?

Sim. Uma correção de bug muda o produto, então lançá-la é uma atualização. Pelo versionamento semântico, uma correção compatível com versões anteriores é uma release de patch, por exemplo da 4.2.0 para a 4.2.1.

Se o leitor precisa fazer alguma coisa é outra pergunta, e a nota deve respondê-la. Uma correção que muda o que um chamador correto observa está perto de um breaking change, e breaking changes explica onde fica essa linha.

Quando uma correção merece entrada própria e quando é uma correção menor?

Dê entrada própria a uma correção quando um usuário poderia ter notado o bug, perdido tempo ou dados com ele, ou criado uma solução alternativa. Agrupe-a em uma lista curta de "Correções menores" quando ninguém fora da sua equipe poderia tê-lo visto. Julgue pela experiência do leitor, qualquer que seja o tamanho do diff.

Ganha entrada própria	Vai na lista de correções menores
Relatado por um cliente ou sentido por muitos	Falha cosmética em uma tela raramente aberta
Causou saída errada, jobs falhos ou trabalho perdido	Erro de digitação, espaçamento, um ícone desalinhado
Exige uma ação do leitor	Correção em uma ferramenta interna ou página de admin
Uma regressão de uma release recente	Falha vista só em ambiente de teste
Toca cobrança, permissões ou dados	Texto de log, atualização de dependência sem efeito para o usuário

Cada linha do grupo ainda deve dizer algo: "Corrigidos alguns problemas de interface" é um espaço reservado.

Como escrever sobre uma regressão?

Nomeie a release que a introduziu, chame-a de regressão e dê a release que a corrige. Quem foi atingido pelo bug já sabe que quebrou, então uma admissão curta e direta serve melhor que uma redação vaga.

Por exemplo: "Resultados de busca para consultas com hífen voltavam vazios na 4.1.0. Isso está corrigido na 4.1.1. Se você mudou suas consultas para evitar hífens, pode voltar ao que era."

"Confiabilidade da busca melhorada" soa como evasiva para quem perdeu uma tarde com o bug. Se a causa ainda está sendo confirmada, digam isso, como orienta o guia de release notes de emergência: nunca deixe a nota soar mais certa do que a equipe está.

Como anunciar uma correção de segurança?

Declare a gravidade com clareza, nomeie as versões afetadas e a versão que as corrige, diga a urgência da atualização e inclua o identificador CVE, se houver. Publique detalhes só quando os usuários puderem agir sobre a correção, seguindo um processo de divulgação coordenada quando houve um relator.

A sequência importa: o relator avisa em particular, vocês lançam a correção e a nota pública sai quando os usuários podem se proteger. O processo de divulgação coordenada de vulnerabilidades da CISA coordena relato, análise e divulgação pública de vulnerabilidades. As regras da CVE Numbering Authority governam como os registros CVE são atribuídos e publicados, e no GitHub um advisory de segurança do repositório permite redigir o aviso em particular e pedir um identificador.

Uma entrada de segurança costuma levar quatro fatos:

O que um atacante poderia fazer, em uma frase e sem prova de conceito.
As versões afetadas e a versão que corrige.
A urgência: "atualize hoje" ou "atualize na sua próxima release".
Se vocês viram exploração, e o crédito ao relator, se ele concordou.

Deixe de fora os passos do exploit.

O que uma nota deve dizer sobre uma correção de perda de dados?

Diga quais dados foram afetados, como saber se os seus foram e se podem ser recuperados. "Nenhuma ação necessária" raramente é verdade aqui, e a primeira pergunta do leitor é "meus dados sumiram?".

Uma entrada útil dá a condição que perdeu dados ("excluir uma pasta enquanto uma sincronização rodava"), a janela em que isso era possível, uma forma de conferir ("abra a Lixeira e procure itens de 3 a 9 de setembro") e o caminho de recuperação. Se os dados não podem ser recuperados, digam isso. Contatem também os clientes afetados diretamente, porque a release note não deve ser o único lugar em que alguém descobre que seus dados foram atingidos.

Por que "Correções de bugs e melhorias de desempenho" é uma nota ruim?

Não dá ao leitor nada sobre o que agir e esconde as correções que alguém esperava. Um cliente que relatou um travamento não sabe se foi corrigido, e um cliente com uma solução alternativa não sabe se deve removê-la.

Há duas alternativas honestas. Se uma release não tem nada que um leitor pudesse notar, não publiquem notas para ela e deixem o changelog guardar o registro. Se tem correções, listem-nas nos termos do leitor:

Antes:
  Correções de bugs e melhorias de desempenho.

Depois:
  Corrigido: a exportação CSV falhava em projetos sem tags.
  Corrigido: o modo escuro escondia o cursor no campo de
  comentário.
  Mais rápido: o painel abre mais depressa em workspaces
  com mais de 100 projetos.

De onde vêm as notas de correção de bugs?

Vêm do pull request que corrigiu o bug e do relato que o originou. Se as palavras de quem relatou viajam com a correção, metade do sintoma já está escrita.

Pedido de funcionalidade ou bug explica por que classificar bem um relato decide quem é o dono dele. No Changeloop, um bug relatado pelo widget vira uma issue do GitHub com a etiqueta bug, e a entrada do changelog é redigida a partir do pull request integrado e retida para uma pessoa aprovar antes de publicar. O template de release notes dá a mesma forma de entrada para escrever à mão: sintoma, alcance, janela, ação.

FAQ

O que as release notes de correção de bugs devem incluir? Cada entrada deve nomear o sintoma que o usuário viu, quem foi afetado, desde qual release ou data, se a correção é completa e o que o leitor precisa fazer, incluindo "nada".

Toda correção de bug deve ser listada nas release notes? Não. Liste as que um usuário poderia ter notado, perdido tempo com elas ou contornado, e agrupe as correções cosméticas ou internas em uma lista curta de "Correções menores". O changelog guarda todas as correções para quem precisar consultar uma.

Como escrever release notes para um bug que você mesmo introduziu? Diga que foi uma regressão, nomeie a release que a introduziu e a release que a corrige, e diga aos leitores se podem remover alguma solução alternativa. Uma declaração direta lê melhor que uma redação suavizada.

Como conferir as release notes de um produto que você usa? Procure uma página de changelog ou release notes ligada no menu de ajuda, no rodapé ou na documentação do produto, ou na aba de releases do repositório, no caso de projetos open source.

Como pedir feedback aos clientes em um produto de software

Fri, 02 Oct 2026 00:00:00 GMT

Para pedir feedback aos clientes em um produto de software, faça uma pergunta específica sobre algo que o usuário acabou de fazer, no lugar onde ele fez. "Como foi exportar esse relatório?" logo depois de uma exportação recebe resposta. "Conte o que você acha do nosso produto" no rodapé recebe silêncio. O resto desta página reúne os momentos, os canais e as frases exatas.

A maior parte dos conselhos sobre o assunto é escrita para lojas e centrais de atendimento. Uma equipe de software sabe exatamente o que o usuário fez um segundo atrás, então a pergunta pode ser sobre isso.

Momento	Onde perguntar	Pergunta pronta para usar
Logo depois de concluir uma tarefa	No app, ao lado do resultado	"Essa exportação fez o que você precisava?"
Depois do primeiro uso de uma funcionalidade nova	No app, uma única vez	"O que você queria fazer com a Edição em Lote?"
Depois que um ticket de suporte é resolvido	Na própria conversa de suporte	"Isso resolveu, ou ainda tem algo estranho?"
Depois que o usuário trava ou abandona um fluxo	E-mail, um dia depois	"Você parou no passo 3 da configuração. O que atrapalhou?"
Depois de 30 dias de uso regular	E-mail de uma pessoa com nome	"Qual é a única coisa que você mudaria?"
Quando o usuário cancela	No fluxo de cancelamento	"O que fez você decidir sair hoje?"
Depois que você lança o que ele pediu	Onde ele pediu	"Você pediu importação de CSV. Já está no ar. Ela cobre o seu caso?"

Qual é a hora certa de pedir feedback?

A hora certa é logo depois que o usuário termina algo, enquanto o detalhe ainda está na cabeça dele. Uma pergunta que vem depois de uma ação recebe uma resposta sobre essa ação. Uma pergunta que aparece do nada recebe uma resposta sobre o humor da pessoa naquele momento, ou nenhuma resposta.

Não pergunte no cadastro, porque ninguém usou nada ainda. Não pergunte no meio de uma tarefa, porque você interrompe justamente aquilo que quer entender. Depois que a pessoa respondeu, deixe-a em paz até ter algo para contar de volta.

Onde pedir feedback aos clientes?

Pergunte no lugar em que a experiência aconteceu. Um aviso dentro do app serve para uma pergunta sobre uma tela. A conversa de suporte serve para uma pergunta sobre uma correção. O e-mail serve para uma pergunta sobre uma semana de uso, ou sobre um fluxo que a pessoa abandonou. Uma ligação serve para as perguntas que você não consegue prever.

Cada canal traz um tipo diferente de resposta:

No app: respostas curtas, imediatas e específicas, mas só de quem está presente. Você não ouve nada de quem já foi embora.
Conversa de suporte: vem de pessoas que já estavam frustradas o suficiente para escrever. Ótimo para achar o que está quebrado, ruim para avaliar o resto do produto.
E-mail: respostas mais longas de menos gente, e o único jeito de alcançar usuários que ficaram em silêncio. Escreva como um bilhete curto de uma pessoa com nome, com uma única pergunta.
Entrevista: o jeito de entender por que as pessoas fazem o que fazem. Peça que mostrem como trabalham e fique quieto enquanto isso.

Qualidade do sinal de feedback explica como pesar o que cada canal diz.

Como pedir feedback de forma profissional?

Seja específico sobre a coisa, diga por que está perguntando e faça a resposta custar menos de um minuto. Um pedido profissional nomeia o momento, deixa claro que uma pessoa vai ler a resposta e não pede desculpas pela interrupção.

Nomeie a ação exata ("a exportação que você acabou de fazer"), peça uma única coisa, use um campo de texto livre sem campos obrigatórios e assine com o primeiro nome.

Qual é uma boa frase para pedir feedback?

Uma boa frase é uma pergunta sobre um momento específico que dá para responder em poucas palavras. Compare as duas colunas abaixo. As da esquerda podem ser respondidas com um dar de ombros. As da direita exigem que a pessoa se lembre de algo real.

Pedido fraco	Pedido mais forte
"Algum feedback?"	"Qual foi a parte mais difícil de configurar isso?"
"O que você acha do nosso produto?"	"Para que você usou isso na semana passada?"
"Avalie sua experiência de 1 a 10."	"Você conseguiu fazer hoje o que veio fazer?"
"Diga como podemos melhorar."	"O que atrasou você esta semana?"
"Você nos recomendaria?"	"Para quem você mostrou isso por último, e o que disse?"

Outra que funciona em quase qualquer lugar: "O que você usa no lugar quando isso não atende?" Ela revela o concorrente de verdade, que muitas vezes é uma planilha.

Quais são as piores formas de pedir feedback?

Os piores pedidos são amplos, cedo demais, longos ou tendenciosos. Todos têm o mesmo problema: a pessoa não consegue responder sem fazer o raciocínio que deveria ter sido seu.

"Responda nossa pesquisa de 20 perguntas." Quem termina é quem tem mais tempo livre ou as opiniões mais fortes.
Um pop-up na primeira página depois do login. O usuário veio fazer algo e você bloqueou. Fechar é a única resposta sensata.
"Adoraríamos ouvir você!" sem nenhuma pergunta. Pede que o usuário invente o assunto.
Uma pergunta tendenciosa: "O quanto você ama o novo painel?" Você ganha concordância e não aprende nada.
Uma nota sem pergunta de acompanhamento. Um 6 em 10 conta o humor. Não diz o que mudar.
Perguntar e depois sumir. Isso custa a próxima rodada, tratada mais adiante.

Como se chama o feedback do cliente sobre um produto?

O feedback sobre um produto costuma ser chamado de feedback de produto, e se divide em dois tipos. Um relatório de bug diz que algo não funciona como deveria. Um pedido de funcionalidade diz que algo está faltando. A distinção decide quem olha primeiro, e pedido de funcionalidade ou bug traça essa linha. Um terceiro tipo, o elogio, vale guardar e citar com permissão.

Um formulário de feedback que oferece "Bug" e "Pedido de funcionalidade" como primeira escolha já faz essa primeira triagem por você.

O que fazer com as respostas?

Coloque cada resposta onde a equipe já trabalha, com as palavras da pessoa intactas. Uma linha de texto citado vale mais que o seu resumo dela. Classifique por tipo e urgência aproximada, una as repetidas e decida: construir, deixar de lado ou recusar.

Recusar também é uma resposta. "Não vamos construir isso, e aqui está o motivo" encerra a espera, e recusar pedidos de funcionalidade traz a redação para isso. Para a parte de encanamento, rastreamento de pedidos de funcionalidades descreve como levar pedidos de cinco canais para uma única lista. Se vocês recebem pedidos por escrito, um template de solicitação de recurso mantém os pedidos comparáveis.

O widget do Changeloop registra cada envio como uma issue no GitHub, então o feedback chega ao lado do código que vai resolvê-lo. Com qualquer ferramenta a regra é a mesma: uma lista, um responsável, nenhuma resposta esquecida na caixa de entrada de alguém.

Por que contar o que foi lançado?

Mostra à pessoa que responder valeu o tempo dela. Um usuário que contou algo e depois ouve "isso foi lançado, obrigado" tem um motivo para responder de novo. Quem não ouve nada conclui que ninguém lê a caixa.

Então o último passo de pedir feedback é uma resposta. Avise cada pessoa que pediu quando o pedido for lançado, nos termos dela, no canal que ela usou. Fechar o ciclo de feedback do cliente descreve o mecanismo: a entrada publicada no changelog é o que dispara a mensagem, então quem pediu só é avisado quando a mudança já está no ar. No Changeloop, quando o feedback do widget virou uma issue no GitHub e o pull request mergeado a fecha, aprovar a entrada publica um comentário "Shipped" nessa issue e mostra a entrada a quem enviou o pedido no widget; issues abertas à mão e repositórios do GitLab ou Bitbucket não recebem comentário. Nossa documentação lista a configuração do widget e do feed.

Uma resposta pode ser curta: "Você pediu importação de CSV em março. Está no ar hoje, e é assim que funciona." Ela também dá a melhor pergunta seguinte: se cobre o que a pessoa precisava.

Um plano para começar

Escolha um momento da tabela no início, aquele em que os usuários mais costumam ter sucesso ou desistir. Escreva uma pergunta para ele, coloque-a em um único canal e leia todas as respostas por duas semanas antes de adicionar um segundo aviso. Responda a quem lhe deu algo concreto.

FAQ

Com que frequência pedir feedback aos clientes? Ligue os pedidos a eventos, não a um calendário. Um usuário deve ver no máximo um aviso por semana, e nenhum logo depois de responder a um. A mensagem seguinte ao feedback deve ser uma resposta sobre o que aconteceu com ele.

Como pedir feedback sem irritar os usuários? Pergunte depois de uma tarefa, nunca no meio de uma, limite-se a uma pergunta e facilite o descarte. Respeite um descarte por algumas semanas.

Vale oferecer um incentivo por feedback? Normalmente não é preciso. Uma pergunta específica e uma resposta visível pesam mais que um vale-presente, e incentivos atraem quem quer a recompensa. Guarde-os para entrevistas, em que você pede 20 minutos do tempo de alguém.

E se ninguém responder? Estreite a pergunta e aproxime-a do momento, por exemplo uma tela, perguntada logo depois de usada. Se continuar quieto, mande e-mail direto a alguns usuários e use essas conversas para escrever avisos melhores.

Exemplos de roadmap de produto: seis formatos e como falham

Fri, 02 Oct 2026 00:00:00 GMT

Os exemplos de roadmap de produto que valem a pena copiar se dividem em seis formatos: Now/Next/Later, uma linha do tempo trimestral, um roadmap por temas, um roadmap por resultados, um roadmap público e um roadmap interno de releases. Cada um responde a uma pergunta diferente para um leitor diferente, então o melhor exemplo é o que combina com quem vai ler o seu. O layout é a última coisa a decidir.

Todos os exemplos abaixo são de um produto inventado, um app de tarefas para equipes pequenas, e todos os itens são fictícios. O ponto é a forma: o que entra em cada espaço, como é uma entrada de verdade e o que faz aquele formato quebrar depois de um trimestre.

Quais são bons exemplos de roadmap de produto?

Um bom exemplo de roadmap é curto, tem um leitor definido e faz um único tipo de promessa. Escolha o formato pela promessa que vocês estão dispostos a cumprir: uma direção, uma data, um tema de trabalho, um resultado, um compromisso público ou um cronograma de entrega.

Formato	Feito para	Funciona quando	Falha quando
Now/Next/Later	A empresa inteira	Os planos mudam com frequência	"Next" enche e vira uma fila
Linha do tempo trimestral	Vendas, suporte, diretoria	As datas são restrições reais	As datas escorregam e ninguém atualiza
Por temas	Liderança, novos contratados	Vocês querem explicar o porquê	Os temas ficam tão amplos que qualquer item cabe
Por resultados	Produto e engenharia	O objetivo é mensurável	A métrica não tem dono nem dados
Público	Clientes	Vocês conseguem mantê-lo pequeno	Vira um depósito de backlog
Interno de releases	Engenharia, QA, suporte	Várias equipes entregam juntas	É confundido com estratégia

Como é cada exemplo de roadmap de produto?

Cada formato abaixo aparece com entradas realistas, seguidas de para quem ele serve, quando se sustenta e como costuma falhar.

Now/Next/Later

NOW (em construção neste mês)
  Visões salvas na caixa de entrada
  Exportação CSV que funciona em contas grandes
NEXT (decidido, ordem não definida)
  SSO para o plano Team
  Notificações no Slack
LATER (uma direção, sem compromisso)
  App mobile
  Log de auditoria

Este serve para uma empresa que não quer prometer datas, o que combina com muitas equipes em fase inicial. Ele se sustenta porque as três colunas descrevem o grau de certeza: "now" está em andamento, "next" está decidido, "later" é uma esperança. Ele falha quando "later" vira o lugar onde se guarda toda ideia que ninguém quer recusar, e quando "next" ganha, sem alarde, uma ordem e uma data sem que ninguém o chame de cronograma.

Linha do tempo ou roadmap trimestral

Q4 2026
  Out   Visões salvas na caixa de entrada
  Nov   Beta de SSO com cinco parceiros de design
  Dez   SSO em disponibilidade geral
Q1 2027
  Jan   Notificações no Slack
  Mar   Log de auditoria (somente exportação)

Este serve para vendas, suporte e financeiro, que precisam planejar em torno de alguma coisa. Funciona quando as datas são restrições reais, como um contrato, uma conferência ou um prazo de compliance. Falha quando as datas são palpites, porque um mês no roadmap vira promessa em uma apresentação de vendas em poucas semanas. Se usarem este formato, marquem cada trimestre como comprometido ou previsto, e deixem o segundo trimestre visivelmente mais vago que o primeiro.

Roadmap por temas

TEMA: Experiência da primeira semana
  Importar de CSV e Trello
  Templates iniciais
TEMA: Pronto para equipes maiores
  SSO
  Log de auditoria
  Permissões por papel
TEMA: Menos passos manuais
  Notificações no Slack
  Tarefas recorrentes

Este serve para atualizações da liderança e para quem acabou de entrar, porque explica por que o trabalho existe antes de listá-lo. Se sustenta quando cada tema corresponde a um motivo pelo qual um cliente se importaria. Falha quando os temas são tão largos ("Crescimento", "Qualidade") que todo item cabe debaixo de todos eles, e nesse ponto o agrupamento não explica nada.

Roadmap por resultados

META: Mais equipes novas concluem a configuração
  Métrica: configuração em até 7 dias, de 40% para 55%
  Apostas: importar de CSV, templates iniciais
META: Menos tickets de suporte sobre exportações
  Métrica: tickets de exportação por semana, de 30 para 10
  Apostas: correção da exportação em contas grandes,
           página de status de exportação

Os números são ilustrativos, e o que importa é o layout: uma meta, uma métrica com ponto de partida e alvo, e as apostas que vocês vão tentar. Serve para equipes de produto e engenharia que têm a confiança para escolher a solução. Funciona quando a métrica existe e alguém é dono dela. Falha quando a meta não é mensurável, ou quando as "apostas" são a mesma lista de funcionalidades de antes com uma frase de resultado colada por cima.

Roadmap público voltado ao cliente

PLANEJADO
  Visões salvas na caixa de entrada
EM CONSTRUÇÃO
  Notificações no Slack
LANÇADO
  Exportação CSV para contas grandes

Este é o menor formato, e é o que faz a promessa mais forte. Serve para clientes, que querem saber se o pedido deles foi ouvido. Se sustenta com pouquíssimos itens, sem datas e com títulos escritos nas palavras do cliente. Falha como depósito de backlog: cada "talvez" listado é uma promessa que alguém vai cobrar depois. A mecânica de manter um a partir do seu issue tracker está em roadmap público em três colunas, então não é repetida aqui.

Roadmap interno de releases

Release	Alvo	Responsável	Depende de	Status
5.2	14 out	Plataforma	Upgrade do serviço de auth	Código completo
5.3	11 nov	Inbox	API de visões salvas	Em andamento
5.4	9 dez	Plataforma	Contrato com o fornecedor de SSO	Bloqueado

Este serve para engenharia, QA e suporte, que precisam saber o que sai junto e o que bloqueia o quê. Funciona quando é preciso até a semana e tem um responsável por linha. Falha quando alguém o confunde com estratégia: um cronograma de entrega diz o que está saindo e quando, e não diz nada sobre se essas releases eram as apostas certas.

Qual formato de roadmap de produto escolher?

Escolha primeiro pelo leitor, depois pela quantidade de certeza que vocês realmente têm. Se não conseguem dizer quem lê o roadmap e que decisão ele ajuda a tomar, nenhum dos exemplos acima vai salvá-lo.

Clientes perguntando "vocês me ouviram?" Use o formato público e mantenha-o em poucos itens.
Vendas e suporte perguntando "posso passar uma data ao cliente?" Use a linha do tempo trimestral, com comprometido e previsto claramente separados.
A liderança perguntando "por que este trabalho?" Use temas, ou resultados se vocês têm os dados.
Uma equipe que muda de direção todo mês. Use Now/Next/Later e resista a colocar datas.
Engenheiros perguntando "o que sai quando?" Use o roadmap de releases e mantenha-o separado do estratégico.

A maioria das equipes acaba com dois: um roadmap estratégico em um dos quatro primeiros formatos e, por baixo dele, um cronograma de releases. Um roadmap público é então uma visão filtrada do estratégico, mostrando apenas aquilo pelo qual vocês aceitam ser cobrados.

Como escrever um roadmap de produto?

Escreva um roadmap nomeando o leitor, escolhendo o formato que responde à pergunta dele, listando apenas os itens que vocês defenderiam em uma reunião e dando a cada item um status e um responsável. Depois decida com que frequência ele será revisado, antes de publicá-lo.

Nomeie o leitor e a decisão. "O suporte decide o que dizer aos clientes sobre SSO" é um motivo. "Todo mundo deveria ver o roadmap" não dá nada para projetar.
Comece pelo que vocês já sabem. Pedidos em aberto, ranqueados por uma regra que vocês conseguem explicar, são matéria-prima melhor que um brainstorm.
Escreva cada item como um resultado para o cliente. "Manter um filtro que você usa muito" soa melhor que "Implementar persistência de visões salvas", e diz ao cliente se o problema é dele.
Decida o que o roadmap não vai conter. Datas, estimativas e um backlog de ideias são as três exclusões habituais.
Defina uma data de revisão. Um roadmap sem revisão agendada tem um funeral não agendado.

Como manter um roadmap de produto atualizado?

Mantenha um roadmap atualizado movendo os itens quando o trabalho se move, a partir do mesmo lugar em que o trabalho é acompanhado, e registrando o que aconteceu quando um item é lançado ou descartado. Um roadmap que alguém atualiza à mão em outra ferramenta fica velho porque não é o trabalho diário de ninguém.

A fonte da verdade mais barata é o issue tracker. Se cada coluna do roadmap corresponde a uma etiqueta na issue, o roadmap muda quando a etiqueta muda, e nada é redigitado. A versão do Changeloop usa as etiquetas roadmap:planned, roadmap:building e roadmap:shipped, e quando uma issue carrega duas, vence a mais avançada. Mover um cartão para lançado continua sendo uma troca de etiqueta própria, então façam disso parte da revisão em que vocês aprovam a entrada do changelog.

Essa entrada é a outra metade. Quando um item é lançado, o changelog diz o que mudou nos termos do cliente, e quem pediu pode ser avisado. Fechar esse ciclo é o objetivo do ciclo de feedback do cliente, e o roadmap é o trecho desse ciclo que o cliente enxerga antes de qualquer lançamento. Se vocês descartarem um item, digam; um "não" público encerra esse pedido também, e recusar pedidos de funcionalidade mostra como formulá-lo. Equipes que querem ver como ficam as entradas prontas podem consultar exemplos de changelog.

FAQ

Qual é o formato de roadmap de produto mais simples? Now/Next/Later. Tem três colunas, não precisa de datas e agrupa os itens por grau de certeza. Para uma equipe pequena que muda de direção com frequência, é também o formato mais difícil de errar de forma constrangedora.

Quantos itens um roadmap de produto deve ter? Menos do que vocês pensam. Menos de dez itens somando todas as colunas bastam para um roadmap público, e um estratégico interno raramente precisa de mais de uma dúzia. Acima disso, é um backlog com um cabeçalho mais bonito.

Um roadmap de produto deve incluir datas? Só se as datas forem restrições reais, e mesmo assim apenas para o trimestre mais próximo. Além disso, use colunas ou temas. Uma data no roadmap vira compromisso em uma conversa de vendas, quer vocês queiram ou não.

Qual é a diferença entre um roadmap de produto e um plano de releases? Um roadmap diz o que vocês pretendem construir e por quê. Um plano de releases diz qual build sai em que data e quem é o responsável. O roadmap muda quando a estratégia muda, e o plano de releases muda quando o trabalho muda.

Processo de gerenciamento de releases para entregas rápidas

Fri, 02 Oct 2026 00:00:00 GMT

Um processo de gerenciamento de releases é o conjunto de passos que leva uma mudança de "integrada" a "rodando em produção e explicada às pessoas que ela afeta". Para uma equipe que entrega com frequência, resume-se a sete passos: planejar o escopo, isolar a mudança, compilar e testar, aprovar, fazer o deploy e verificar, comunicar e revisar. Cada passo precisa de um responsável nomeado e de um critério de saída, ou deixa de acontecer sem alarde.

Este guia pressupõe uma equipe de 5 a 50 engenheiros que fazem deploy toda semana ou todo dia e querem que o processo fique fora do caminho.

Passo	Responsável	Critério de saída
1. Planejar o escopo	Produto ou tech lead	A lista de mudanças desta release está escrita, e o que é arriscado está marcado
2. Branch ou flag	O engenheiro dono da mudança	O trabalho está em um branch de vida curta ou atrás de uma flag, então a main continua liberável
3. Compilar e testar	CI, com o autor de plantão para falhas	Pipeline verde no commit exato que vai ser entregue
4. Aprovar	Revisor, mais o release manager nas mudanças arriscadas	Revisão feita, caminho de rollback nomeado, go ou no-go registrado
5. Deploy e verificação	Release manager ou engenheiro de plantão	Deploy feito, smoke checks passam, taxa de erro e latência batem com a linha de base pré-release
6. Comunicar	Quem entende a mudança, editado por alguém que não entende	Release notes publicadas onde os usuários leem, suporte e vendas avisados
7. Revisar	Release manager	Métricas lidas, tudo o que deu errado tem dono e correção

O que é o processo de gerenciamento de releases?

É o caminho repetível que uma mudança segue até chegar aos usuários: escopo, build, teste, aprovação, deploy, verificação, anúncio e retrospectiva. O objetivo de escrevê-lo é que toda release siga o mesmo caminho, de modo que alguém de férias, um novo contratado ou um engenheiro de plantão às 2 da manhã possa executá-lo sem perguntar a ninguém como funciona.

Quais são os diferentes tipos de gerenciamento de releases?

Há três tipos práticos: deploy contínuo, releases agendadas e gerenciamento de mudanças regulado. Eles diferem em quanto acontece antes de uma release e em quanto é automatizado. O deploy contínuo entrega cada mudança integrada, as releases agendadas agrupam mudanças em um trem e o gerenciamento de mudanças regulado acrescenta aprovação formal e trilha de auditoria.

	Deploy contínuo	Releases agendadas	Gerenciamento de mudanças regulado ou ITIL
Unidade da release	Um pull request integrado	Um lote, semanal ou quinzenal	Uma solicitação de mudança
Passo de escopo	Implícito, o merge é o escopo	Reunião de planejamento da release	Registro de mudança com classificação de risco
Aprovação	Code review mais checagens automáticas	O release manager aprova o lote	Comitê consultivo de mudanças ou aprovador delegado
Controle de risco	Feature flags, canários, rollback rápido	Soak em staging, release candidate	Plano de retorno documentado, janela de manutenção
Cadência típica	Muitas por dia	Semanal a mensal	Definida pelo calendário de mudanças
Ponto fraco	Ninguém conta aos usuários o que mudou	Lotes grandes escondem a mudança que quebrou algo	O tempo de processo supera a própria mudança

A maioria das equipes é uma mistura. Um produto SaaS pode fazer deploy contínuo enquanto o app mobile sai em um trem semanal, e o único serviço de pagamentos que os auditores acompanham segue um registro formal de mudança. Escolha o tipo por serviço, não por empresa. Onde as mudanças são expostas aos poucos, a release e o anúncio viram eventos separados, caso tratado em release notes de feature flag.

Quais são as responsabilidades de um release manager?

Um release manager é dono do caminho que uma mudança percorre até a produção. Ele mantém o calendário de releases, decide se uma mudança está pronta, executa ou supervisiona o deploy, toma a decisão de rollback, garante que os usuários sejam avisados e conduz a revisão depois.

Antes da release, confirma o escopo e checa se toda mudança arriscada tem um caminho de rollback. Durante ela, executa o checklist de deploy, acompanha os primeiros minutos das métricas de produção e chama o rollback cedo. Depois, confirma que as notas saíram e registra o que corrigir no processo.

Em uma equipe pequena, revezem o papel toda semana e escrevam o checklist para que ninguém precise de conhecimento tribal. Um monorepo com muitos pacotes lançados de forma independente costuma precisar de um responsável por pacote, ou o papel vira um gargalo.

Quais são os principais KPIs de gerenciamento de releases?

Acompanhe as métricas de entrega de software da DORA e acrescente uma sua: quanto tempo leva até os usuários serem avisados. A pesquisa da DORA identifica cinco métricas, divididas em vazão (lead time de mudança, frequência de deploy, tempo de recuperação de deploy com falha) e instabilidade (taxa de falha de mudança, taxa de retrabalho de deploy).

O guia da DORA as define em termos simples (dora.dev, software delivery metrics):

KPI	O que mede	O que observar
Lead time de mudança	Tempo do commit no controle de versão até o deploy em produção	Um número crescente costuma indicar filas em revisão ou aprovação
Frequência de deploy	Com que frequência vocês fazem deploy, ou o intervalo entre deploys	Frequência em queda significa que os lotes estão crescendo
Tempo de recuperação de deploy com falha	Tempo para se recuperar de um deploy que exige intervenção imediata	Problemas de rollback e de alertas aparecem aqui
Taxa de falha de mudança	Parcela dos deploys que exigem rollback ou hotfix	Sobe quando os lotes são grandes demais ou o teste é fraco
Taxa de retrabalho de deploy	Parcela dos deploys não planejados e causados por um incidente em produção	Sinal de que as correções saem mais rápido que as lições
Tempo até os usuários serem avisados	Minutos do deploy em produção até uma nota publicada para o usuário	Meçam vocês mesmos, nenhum framework fornece

Materiais mais antigos listam quatro métricas-chave e chamam a recuperação de "time to restore". O guia atual usa as cinco acima.

O mesmo guia alerta contra tratá-las como metas. Definir um objetivo como "tudo faz deploy várias vezes por dia até o fim do ano" convida as equipes a manipular os números, e as métricas devem ser lidas por aplicação ou serviço, não misturadas na empresa toda. O conselho prático dele para melhorar todas é reduzir o tamanho de cada mudança, porque mudanças menores são mais fáceis de revisar, de levar pelo pipeline e de recuperar.

Como a comunicação da release se encaixa no processo de gerenciamento de releases?

É o passo seis, e tem responsável e critério de saída como todos os outros: notas publicadas onde os usuários leem e equipes internas avisadas. É o passo que as equipes mais pulam, porque a ferramenta de deploy reporta sucesso no instante em que o código está no ar.

O jeito mais barato de manter esse passo em dia é escrever a entrada quando a mudança é integrada, não quando a release sai. O pull request já contém o título, o autor, a issue ligada e o contexto. Um rascunho construído a partir dele é editado, não escrito de memória uma semana depois. Essa é a ideia por trás da automação de changelog: derivar um rascunho no merge, retê-lo para uma pessoa aprovar e depois publicá-lo em todo lugar a partir de uma única fonte. O Changeloop funciona assim, redigindo entradas a partir de pull requests integrados com IA e retendo-as para aprovação antes de publicar qualquer coisa.

Duas variações merecem planejamento prévio. Suporte e vendas precisam de uma nota diferente da dos clientes, e para isso servem as release notes internas. Uma release causada por um incidente não tem tempo para o ciclo normal de redação, então mantenham um template curto pronto, como descrito em release notes de emergência. O template de release notes dá uma forma inicial para a versão voltada ao cliente.

Como manter o processo leve?

Automatize todo critério de saída que uma máquina possa checar e reserve as pessoas para os julgamentos. Um pipeline verde, um marcador de deploy nos dashboards e um rascunho de entrada de changelog por pull request integrado são checáveis. Se um plano de rollback é crível, ou se as notas fazem sentido para um cliente, é coisa para uma pessoa.

Para testar o processo, escolha uma release do mês passado e pergunte se alguém de fora da equipe conseguiria dizer, só pelo registro escrito, o que foi entregue, quem aprovou, como foi verificado e quando os usuários foram avisados. Qualquer lacuna é a sua próxima melhoria.

FAQ

Qual é a diferença entre gerenciamento de releases e gerenciamento de mudanças? O gerenciamento de releases leva um conjunto de mudanças a ser compilado, testado, implantado e anunciado. O gerenciamento de mudanças, no sentido ITIL, é o processo de aprovação e de risco em torno de cada mudança. Equipes que entregam com frequência incorporam a aprovação ao code review e às checagens automáticas.

Com que frequência devemos fazer releases? Tão frequentemente quanto seus testes e seu caminho de rollback permitirem, o que para muitas equipes web é todo dia ou mais. A orientação da DORA é reduzir o tamanho de cada mudança, já que mudanças pequenas são mais fáceis de revisar e de recuperar.

Equipes pequenas precisam de um release manager? Precisam das responsabilidades, mas não necessariamente do título. Revezem o papel entre os engenheiros, deem à pessoa do rodízio um checklist escrito e garantam que alguém seja dono de cada um dos sete passos.

O que um checklist de release deve incluir? Escopo confirmado, pipeline verde no commit que vai ser entregue, caminho de rollback nomeado, aprovação registrada, smoke checks após o deploy, métricas comparadas com a linha de base, release notes publicadas, suporte avisado e uma revisão agendada. Mantenha em uma página.

Exemplos de release notes para cada tipo de mudança

Fri, 02 Oct 2026 00:00:00 GMT

Os melhores exemplos de release notes são curtos, dizem quem é afetado e explicam o que fazer em seguida. Abaixo vai um exemplo para cada tipo de mudança que vocês vão lançar, com o motivo de ele funcionar, para que você copie a forma e troque pelos seus fatos.

Todos os exemplos são inventados, para um app de faturamento fictício chamado Tidepool.

O que bons exemplos de release notes têm em comum?

Eles dizem aos usuários o que mudou e o que, se for o caso, fazer a respeito, nas palavras dos usuários. Cada tipo de mudança tem uma função diferente, então a forma muda de um para outro.

Tipo de mudança	A entrada precisa dizer	Onde fica
Funcionalidade nova	O que o leitor agora pode fazer e quem recebe	Topo das notas
Melhoria	O que ficou mais rápido ou mais fácil, com um número se houver	Depois das funcionalidades
Correção de bug	O sintoma que o leitor viu e que foi corrigido	Depois das melhorias
Breaking change	Quem é afetado, a data, a migração	Sempre em primeiro
Correção de segurança	O que foi exposto, se foi explorado, o que fazer	Em primeiro
Depreciação	O que deixa de existir, a data final, a substituição	Perto do topo
Nota de loja de apps	Uma frase simples por mudança, dentro do limite de caracteres	Página da loja
Nota interna	O que mudou e o que dizer aos clientes	Canais de suporte e vendas

Como é uma boa nota de funcionalidade nova?

Uma boa nota de funcionalidade abre com o que o leitor pode fazer agora e nomeia os planos ou papéis que a recebem. Ela pula a implementação.

Envie faturas no idioma do cliente. Agora você pode escolher um idioma para cada cliente, e as faturas, os lembretes e a página de pagamento dele seguem essa escolha. Francês, alemão, espanhol e português estão disponíveis em todos os planos. Defina na página do cliente, em Preferências de cobrança.

O título é uma frase que o leitor diria em voz alta, e o corpo dá o alcance e o local. Quem lê só a linha em negrito já sabe o que foi lançado. O método completo está em como escrever release notes.

Como é uma boa nota de melhoria?

Uma nota de melhoria descreve uma mudança que o leitor vai sentir e coloca um número medido quando existe um. Sem número, diga o que o leitor não precisa mais fazer.

A lista de faturas carrega cerca de três vezes mais rápido. Contas com mais de 5.000 faturas esperavam cerca de nove segundos pela lista. Agora ela abre em cerca de três. Nenhuma ação necessária.

"Melhorias de desempenho" não diz nada ao leitor, enquanto nove segundos contra três é uma afirmação que ele pode conferir na segunda de manhã. O "Nenhuma ação necessária" final responde à pergunta que todo leitor tem.

Como é uma boa nota de correção de bug?

Uma nota de correção descreve o sintoma que o usuário viu, não a causa no código, e diz se ele precisa refazer alguma coisa. Correções que ninguém notou podem ir na lista no final.

Corrigido: e-mails de lembrete enviados duas vezes na data de vencimento. Alguns clientes recebiam dois lembretes idênticos se a fatura vencia no último dia do mês. Isso foi corrigido. Lembretes já enviados não são afetados, e ninguém precisa reenviar nada.

O título começa com "Corrigido" para quem passa os olhos poder classificar de relance, e a condição real (o último dia do mês) vem logo em seguida.

Como escrever release notes para um breaking change?

Uma nota de breaking change abre com a data e o grupo afetado, e depois dá a migração na mesma entrada. Ela vai em primeiro lugar nas release notes, porque é a única entrada que o leitor não pode perder.

Assinaturas de webhook passam a ser obrigatórias em 1º de dezembro de 2026. A partir dessa data, o Tidepool deixa de enviar payloads de webhook sem assinatura. Isso afeta quem recebe webhooks sem verificar o header Tidepool-Signature. Para migrar, verifique o header usando o segredo em Configurações, Desenvolvedores. Se você já verifica assinaturas, nenhuma ação necessária.

A data está no título, então sobrevive a uma leitura rápida. O grupo afetado é nomeado pelo que faz, e a última frase libera quem já está bem, o que reduz a carga do suporte. O guia de breaking changes explica como decidir se uma mudança conta.

Como é uma nota de correção de segurança?

Uma nota de segurança diz o que foi exposto, se alguém explorou, quem é afetado e o que deve fazer. Mantenha-a factual e calma.

Segurança: links de redefinição de senha podiam ser reutilizados. Entre 3 e 17 de setembro de 2026, um link de redefinição de senha continuava válido depois de usado uma vez. Não encontramos sinais de que isso tenha sido explorado. Está corrigido, e todos os links de redefinição pendentes foram invalidados. Se você pediu uma redefinição nesse período, peça um novo link.

A janela exata permite ao leitor avaliar a própria exposição, e a frase sobre exploração responde à primeira pergunta que qualquer pessoa faz. "Um possível problema" soa como encobrimento, então diga o que vocês sabem.

Como escrever um aviso de depreciação?

Um aviso de depreciação nomeia o que está sendo removido, dá uma data final firme e aponta para a substituição.

O endpoint v1 de faturas está depreciado e termina em 1º de março de 2027. GET /v1/invoices continua funcionando até 1º de março de 2027 e depois retorna 410 Gone. Use GET /v2/invoices, que retorna os mesmos campos mais currency. Respostas da v1 agora incluem um header Sunset com a data final. Um guia de migração lado a lado está na documentação.

O nome do endpoint está no título, porque quem é afetado o procura, e a substituição fica ao lado da remoção. O header Sunset mostra aos desenvolvedores quais chamadas ainda usam a versão antiga. O tratamento mais longo está em depreciar uma API.

Como é uma release note para loja de apps?

Uma nota de loja de apps tem duas ou três frases simples, porque a maioria das pessoas lê só a primeira linha. Abra com a mudança que o usuário notaria.

Escaneie um recibo em papel e o Tidepool preenche valor, data e fornecedor. O modo escuro agora segue a configuração do seu celular. Também corrigimos um travamento ao abrir uma fatura a partir de uma notificação.

A mudança mais útil vem primeiro, e a correção nomeia a situação que travava. Não há número de versão nem "correções de bugs e melhorias". Release notes para apps mobile cobre as regras específicas das lojas.

O que uma nota interna de release deve incluir?

Uma nota interna é a versão para suporte e vendas. Ela acrescenta o que a nota pública deixa de fora: o que dizer e o que evitar prometer.

Faturas em vários idiomas lançadas hoje (todos os planos). Suporte: os clientes definem o idioma em Preferências de cobrança, e faturas existentes mantêm o idioma original. O italiano ainda não está disponível. Vendas: isso está aberto a todos os planos, então não posicionem como upgrade.

Cada público recebe sua própria linha identificada, e a nota traça o limite ("O italiano ainda não está disponível") antes que um cliente pergunte. O artigo sobre release notes internas cobre formato e canais.

Como é uma release note ruim, reescrita?

Uma release note ruim lista o que a equipe fez em vez do que o leitor ganha. Conserte-a movendo o resultado para a frente e apagando o vocabulário interno.

Antes:

v3.8.1 Refatorado o agendador de lembretes. Corrigida uma race condition em ReminderJob. Atualizado bull para 4.12. Melhorias diversas.

Depois:

E-mails de lembrete não saem mais duas vezes. Clientes com fatura vencendo no último dia do mês podiam receber dois lembretes. Isso foi corrigido, e lembretes já enviados não precisam ser reenviados. Nenhuma ação necessária.

Também na 3.8.1: bull atualizado para 4.12.

A atualização de dependência foi para uma linha de rodapé, e a race condition virou um sintoma que um cliente reconheceria.

Como manter release notes consistentes entre releases?

Redija cada entrada quando a mudança é integrada, e peça que uma pessoa a aprove antes de ir ao ar.

O Changeloop funciona assim: redige uma entrada a partir de cada pull request integrado, com IA, e a segura até que uma pessoa a aprove. A etapa de aprovação é onde um editor aplica as regras acima. Para definir o formato antes, comece pelo template de release notes e veja exemplos de changelog para saber como ficam as páginas prontas.

FAQ

O que são release notes novas? Release notes novas são a mensagem publicada com a versão mais recente de um produto, descrevendo o que mudou e o que os usuários precisam fazer. Cobrem funcionalidades, melhorias, correções e breaking changes.

Qual é a diferença entre uma release note e um changelog? O changelog guarda tudo, para quem quer o histórico inteiro. Uma release note escolhe a partir dele: uma release, escrita para os leitores que decidem se ela importa para eles. A comparação completa está em changelog vs release notes.

O que significa release notes? Release notes dizem aos usuários o que mudou em uma release. A expressão cobre qualquer texto que explique o que foi lançado, desde o texto "Novidades" de uma loja de apps até uma página no site de uma empresa.

Qual deve ser o tamanho de cada entrada de release notes? De duas a quatro frases bastam para a maioria das entradas: o resultado, quem é afetado e o que fazer. Um breaking change ou uma correção de segurança pode ser mais longo, porque precisa de uma data ou de uma migração.

Versionamento da API do Stripe: como funciona e o que copiar

Fri, 02 Oct 2026 00:00:00 GMT

O versionamento da API do Stripe funciona por data. Cada conta é fixada em uma versão da API com o nome de uma data de lançamento, e qualquer requisição pode sobrescrever essa fixação com um header Stripe-Version. No momento em que escrevo (outubro de 2026), a versão atual na documentação do Stripe é 2026-09-30.endive, e o mesmo esquema é algo que uma API bem menor pode copiar em um fim de semana.

Todo fato sobre o Stripe abaixo vem das próprias páginas do Stripe, com link no ponto em que é usado.

Mecanismo	O que o Stripe faz	Fonte
Nome da versão	Uma data, mais um nome de release desde 2024 (`2026-09-30.endive`)	Versioning
Versão padrão	Fixada na conta, alterada no Workbench	Versioning
Sobrescrita por requisição	Header `Stripe-Version`, ou a opção do SDK	Upgrades
Webhooks	Renderizados na versão definida no endpoint	Upgrades
Cadência	Releases mensais sem breaking changes, uma release major duas vezes por ano	Versioning
Versões antigas	Mantidas funcionando por módulos internos de mudança de versão	Engineering post

Como funciona o versionamento da API do Stripe?

O Stripe dá a cada conta uma versão padrão da API, e toda requisição que não nomeia uma versão usa essa. Quem chama escolhe quando migrar, alterando o padrão ou definindo uma versão em requisições individuais.

O post de engenharia do Stripe diz que a conta é fixada na primeira vez que faz uma requisição à API: ela é "automatically pinned to the most recent version available", e a partir daí toda chamada recebe implicitamente essa versão.

A string da versão é uma data. Desde a release 2024-09-30.acacia, ela também carrega um nome, como em 2026-09-30.endive. A data ordena as versões, e o nome diz a que família de release major uma versão pertence.

Como escolher a versão em cada requisição?

Envie o header Stripe-Version na requisição, ou defina a versão no SDK. O guia de upgrade do Stripe mostra a forma com header, e a mesma chamada funciona em ambientes live e de teste.

curl https://api.stripe.com/v1/charges \
  -u "$STRIPE_SECRET_KEY:" \
  -H "Stripe-Version: 2026-09-30.endive"

O guia do Stripe observa que, quando você define a versão globalmente ou por requisição em um SDK, os objetos de resposta voltam nessa versão.

O Stripe também recomenda não depender do padrão da conta. Nas palavras dele, especifique a versão em cada requisição, com o header ou com um SDK fixado, para que o seu código decida a versão e não uma configuração de painel.

Os SDKs fixam de forma diferente conforme a linguagem. A documentação diz que as versões recentes das bibliotecas de tipagem dinâmica usam a versão da API que era a mais recente quando aquela release do SDK saiu, e as de tipagem forte (Java, Go e .NET) ficam presas a ela. Instalar uma versão da biblioteca é, na prática, escolher uma versão da API.

O que acontece com os webhooks quando a versão muda?

Um evento de webhook é renderizado na versão da API associada ao endpoint dele, não na versão que o código do seu servidor usa. A documentação do Stripe diz que os eventos usam a versão definida quando o endpoint foi criado e, caso contrário, o padrão da conta. Mudar a versão do seu SDK não muda o que o seu handler de webhook recebe.

O caminho das suas requisições e o caminho dos eventos podem, portanto, estar em duas versões diferentes. Para destinos de eventos, snapshot_api_version só é definido na criação do destino, então uma versão diferente significa um destino novo.

O caminho de upgrade do Stripe para isso é uma execução em paralelo. Crie um endpoint novo na versão de destino, envie os mesmos eventos aos dois, ensine o handler a processar um e ignorar o outro, depois troque e desative o endpoint antigo. Como todo evento chega duas vezes durante a sobreposição, o handler precisa ser idempotente. É um bom padrão para copiar em qualquer API que emite eventos, e um changelog de webhook é onde vocês anunciam as mudanças de payload que tornam isso necessário.

O que são as releases mensais e as major?

Desde a release 2024-09-30.acacia, o Stripe lança uma versão nova da API todo mês sem breaking changes, e emite uma release major nova duas vezes por ano, que começa com uma versão contendo breaking changes. A página de versionamento diz que dá para migrar para qualquer release mensal sem atualizar o código, enquanto uma release major pode exigir mudanças.

As releases major têm nomes. A página de versionamento cita Basil como exemplo, e o anúncio do processo pelo Stripe diz que os nomes vêm de plantas, começando por Acacia, e que as releases mensais mantêm o nome da release major anterior, para que o nome sinalize que migrar para elas é seguro. O changelog do Stripe lista os nomes em uso, e no momento em que escrevo a entrada mais nova é 2026-09-30.endive.

Assim, a data responde "quão nova", e o nome responde "é um limite com breaking change?". O anúncio do Stripe também deixa espaço para exceções: ele se reserva o direito de lançar uma breaking change fora do ciclo quando uma integração seria gravemente afetada sem ela. O anúncio está em Stripe's new API release process.

Qual é a versão mais recente da API do Stripe?

No momento em que escrevo (outubro de 2026), a página de versionamento do Stripe afirma que a versão atual é 2026-09-30.endive, e o changelog dele lista a mesma versão como a mais nova. O Stripe publica uma versão nova todo mês, então qualquer string impressa em um artigo envelhece rápido. Leiam o changelog ao vivo antes de fixar qualquer coisa, e fixem a versão contra a qual vocês testaram.

Como o Stripe mantém versões antigas funcionando?

O Stripe mantém versões antigas vivas escrevendo cada breaking change como um módulo autônomo de mudança de versão e aplicando os módulos de trás para a frente, a partir da forma mais nova dos dados. O post de engenharia sobre versionamento de API descreve o mecanismo.

Cada módulo declara o que muda, documenta a mudança e inclui uma função de transformação. O post dá o exemplo de um campo que muda de string para hash. Para montar uma resposta, o sistema descobre a versão de destino, depois volta no tempo e aplica cada módulo que encontra pelo caminho até chegar a essa versão.

Dois efeitos colaterais decorrem desse desenho, e o post nomeia os dois. Como os módulos declaram os campos e recursos que tocam, o Stripe consegue gerar o changelog da API a partir deles no deploy. E como a versão da conta é conhecida, a documentação pode se adaptar a ela e avisar sobre mudanças incompatíveis com versões anteriores desde aquela versão.

Quanto custa, e o que uma API menor deve copiar?

Versionar custa atenção de engenharia, e o Stripe admite isso. O post de engenharia reconhece um peso de manutenção e declara o objetivo de que, quanto menos for preciso pensar no comportamento antigo ao escrever código novo, melhor. Ele também descreve revisões leves de API antes do lançamento, para evitar precisar de uma mudança de versão.

Uma API pequena não pode pagar uma cadeia de módulos para cada versão antiga, e não precisa de uma. Copie as partes que carregam o valor:

Versões com data. Uma data não exige julgamento sobre o que conta como "major", e quem chama consegue lê-la. O artigo de melhores práticas de versionamento de API compara isso com esquemas por URL e por header.
Um padrão fixado. Fixe a conta ou a chave na versão do primeiro uso, para que a API nunca mude sob uma integração que funciona.
Uma sobrescrita por requisição. Um header que deixa quem chama testar uma versão nova em uma chamada, em produção, antes de se comprometer.
Uma versão no endpoint de webhook. Os payloads de eventos são o lugar onde quem chama mais se surpreende.
Uma entrada de changelog por versão. Faça-a nomear a versão, a data, quem é afetado e o que fazer. O que conta como breaking é o teste para o que pertence a uma versão nova, e o artigo sobre changelog de API cobre a entrada em si.

Pulem a cadeia de módulos até que o número de versões suportadas a imponha. Duas ou três versões ativas se resolvem com alguns branches e uma data de sunset, o que encerrar uma versão de API detalha.

Se vocês publicam um changelog com datas, o histórico de versões é tão bom quanto as entradas dele. No Changeloop, uma entrada em rascunho é criada a partir de cada pull request integrado e retida para uma pessoa aprovar antes de ser publicada na página e no feed do changelog. É ali que uma entrada por versão é escrita, e o único portão humano é a revisão que diz o que quem chama precisa fazer.

FAQ

Qual é a versão mais recente da API do Stripe? No momento em que escrevo (outubro de 2026), a página de versionamento do Stripe afirma que a versão atual é 2026-09-30.endive. O Stripe emite uma versão nova todo mês, então confira o changelog antes de fixar, e escreva a versão no seu código em vez de depender do padrão da conta.

Como definir a versão da API do Stripe em uma requisição? Envie o header Stripe-Version, por exemplo Stripe-Version: 2026-09-30.endive, ou defina a versão no seu SDK de servidor, globalmente ou por requisição. Sem nenhum dos dois, a requisição usa a versão padrão da sua conta, que você define no Workbench.

Os webhooks usam a mesma versão da API do Stripe que as minhas requisições? Não necessariamente. Os eventos de webhook usam a versão definida quando o endpoint foi criado e, se nenhuma foi definida, o padrão da conta. Atualizar o SDK não muda o payload que o seu handler de webhook recebe, então atualize os endpoints separadamente e teste-os em paralelo.

O versionamento por data no estilo do Stripe serve para uma API pequena? Versões com data, um padrão fixado, um header por requisição e uma entrada de changelog por versão são baratos e valem a cópia. A cadeia interna de módulos de mudança de versão não vale, até que vocês suportem muitas versões antigas ao mesmo tempo. Comecem com duas versões ativas e uma data de sunset para a mais antiga.

Quem escreve o changelog, e quem deveria

Tue, 22 Sep 2026 00:00:00 GMT

Pergunte a um time quem escreve o changelog e a resposta honesta costuma ser "quem lembrar", que é o mesmo modo de falha que impor uma entrada de changelog no CI existe para consertar em nível mecânico. Mas forçar a existência de uma entrada não decide quem está qualificada para escrever uma boa, e times que pulam essa pergunta tendem a recorrer por padrão a quem for mais fácil de obrigar, geralmente a autora do PR, sem verificar se essa é realmente a pessoa que consegue escrevê-la bem.

Por que a autora do PR não é automaticamente a melhor escritora de changelog?

Porque ela conhece a implementação, não necessariamente o impacto, e esses são tipos diferentes de conhecimento. Onde os conventional commits param cobre essa lacuna pelo lado da mensagem de commit: fix(auth): reject expired refresh tokens está correto e não diz nada a uma cliente, e quem escreveu essa correção é muitas vezes a pessoa menos equipada para traduzi-la, porque passou horas pensando nos termos do bug e perdeu a visão externa do que uma usuária de fato experimentou. Essa é a mesma razão pela qual redatoras técnicas existem como profissão: traduzir implementação em impacto é uma habilidade distinta de ter construído a coisa, e isso exige prática independente de quão boa a desenvolvedora seja no próprio código.

Isso significa que produto ou suporte deveriam escrever cada entrada em vez disso?

Não, porque elas têm a lacuna oposta: sabem o que importa para as usuárias mas nem sempre o que de fato foi lançado, o que produz entradas legíveis mas ocasionalmente erradas em escopo, uma afirmação "agora suporta X" para um recurso ainda atrás de uma flag, ou uma correção descrita como completa quando cobre apenas um de três casos. O modo de falha de entradas escritas por desenvolvedoras é ilegível-mas-preciso; o modo de falha de entradas escritas por PMs é legível-mas-não-verificado. Nenhum papel possui as duas metades do que uma boa entrada precisa.

Papel	Geralmente acerta	Geralmente erra
Desenvolvedora que escreveu o código	O escopo exato do que mudou	Enquadrar isso para alguém que não construiu
PM ou líder de suporte	Por que isso importa para a usuária	Os limites precisos do que de fato foi lançado
Dona dedicada do changelog	Voz consistente, confere o escopo	Precisa de ambas acima para ter com que conferir

Como de fato é um modelo de responsabilidade que funciona?

Um rascunho de quem estiver mais perto da mudança, revisado por quem estiver mais perto da usuária, com uma pessoa nomeada responsável pela formulação final em vez de todo mundo assumir que outra pessoa vai pegar os problemas. O rascunho precisa existir e ser preciso mais do que precisa ser bom; uma frase crua escrita por uma desenvolvedora que diz corretamente o que mudou é um ponto de partida melhor do que uma polida mas não verificada, porque reescrever por clareza é mais fácil do que reescrever por correção. O passo de revisão é onde uma PM ou líder de suporte lê o rascunho e faz a única pergunta que pega a lacuna de legibilidade: eu entenderia isso se não tivesse visto o código.

Deveria ser sempre a mesma pessoa responsável, ou isso roda?

Nomeada e estável vence rotativa, pelo menos para a aprovação final. Uma dona rotativa significa que cada entrada é revisada por alguém que re-deriva as convenções do time do zero, o que é exatamente como a voz vai à deriva de entrada em entrada e uma leitora começa a notar que o changelog foi escrito por um comitê. Uma pessoa, ou um grupo estável muito pequeno, acumula julgamento ao longo do tempo, quando dizer "melhorado" versus nomear o número específico, quando uma correção precisa de sua própria entrada versus se dobrar em um lote, e esse julgamento vale mais do que distribuir o trabalho igualmente.

Rascunho (desenvolvedora, do PR):
"Fixed pagination cursor not respecting the `sort` param
in some edge cases."

Revisado (dona do changelog, conferido com o PR real):
"Corrigido: exportações ordenadas por data podiam
retornar resultados fora de ordem além da primeira
página. Agora consistente em todas as páginas."

Um time pequeno precisa de tanto processo assim para uma linha de texto?

Não os papéis como pessoas separadas, mas os dois passos ainda importam mesmo sozinha. Um time de uma pessoa é tanto a desenvolvedora quanto a revisora, e a disciplina que sobrevive nessa escala é fazer a revisão como uma passada mental separada, não pular direto de escrever a correção para publicar uma descrição dela no mesmo fôlego. A armadilha em pequena escala é pular a segunda passada completamente, não a falta de uma segunda pessoa, porque ninguém de fora a impõe, e a lacuna de precisão que essa passada existe para pegar não desaparece só porque a mesma pessoa poderia teoricamente notar seu próprio ponto cego.

O que acontece quando ninguém é responsável pela entrada final?

O changelog se degrada de forma desigual em vez de falhar abertamente, o que é pior porque ninguém percebe até uma leitora apontar. Algumas entradas permanecem nítidas porque quem as escreveu se importava; outras ficam vagas, "várias melhorias e correções de bugs", porque quem as escreveu estava com pressa e ninguém pegou isso antes da publicação. As restrições de formato do Keep a Changelog pegam desvio estrutural, datas faltando, categorias erradas, mas nada em um template pega uma entrada vaga que está tecnicamente bem formatada, o que é exatamente a lacuna que uma dona nomeada existe para fechar.

FAQ

A dona do changelog deveria ser um papel de engenharia ou de produto? Qualquer um pode funcionar se a pessoa tiver tanto fluência técnica para verificar o escopo quanto distância suficiente da implementação para escrever para uma leitora externa; o cargo importa menos do que se ela consegue fazer as duas metades, ou sabe a quem perguntar sobre a metade que não consegue.

Uma escala rotativa estilo plantão é adequada para a responsabilidade do changelog? Para volume, às vezes, se o time for pequeno demais para uma pessoa revisar tudo; para voz e julgamento, não, porque isso é exatamente o que a rotação corrói. Uma rotação que divide a carga de rascunho enquanto mantém uma revisora estável ganha o benefício sem o desvio.

Qual é o sinal mais rápido de que algo está errado com a configuração atual de responsabilidade? Entradas que são precisas mas ilegíveis, ou legíveis mas erradas em escopo, em um padrão que segue quem as escreveu. Se a qualidade correlaciona com a autora em vez de permanecer consistente, a lacuna está na responsabilidade, não na habilidade de escrever.

A automação reduz o quanto a responsabilidade importa? Ela reduz quanta escrita é necessária, não quanto julgamento é necessário. Automação de changelog cobre o que um pipeline pode gerar com segurança, formatação, publicação, cross-posting; formulação, agrupamento e o que conta como digno de menção continuam sendo decisões humanas independentemente de quanto do pipeline está automatizado.

E se a autora do PR e a revisora discordarem sobre a formulação? A palavra final é da revisora, porque a pergunta que ela está respondendo, uma leitora de fora entenderia isso, é exatamente a que o papel existe para proteger. Isso não torna a leitura da desenvolvedora sem valor: se o desacordo é sobre precisão em vez de formulação, a revisora cede, porque o escopo é a metade que cabe à autora acertar. Separar os dois tipos de desacordo, formulação versus precisão, evita que a maioria deles vire um impasse.

Release notes de emergência sob pressão de tempo real

Tue, 22 Sep 2026 00:00:00 GMT

A maioria das release notes é escrita depois que o código está pronto, revisada com calma, e publicada em um cronograma que não tem nada a ver com quão urgentemente alguém precisa lê-la. Releases de emergência, patches de segurança, bugs de perda de dados, correções de instabilidade, viram todas essas condições de cabeça para baixo ao mesmo tempo: a nota precisa existir antes de a maioria das pessoas normalmente começar a escrevê-la, mal recebe revisão, e é lida por uma leitora ansiosa em vez de uma calma. Como escrever release notes cobre o processo normal; isto é sobre o que muda quando não sobra tempo para segui-lo.

Qual é a única coisa que uma release note de emergência precisa acertar, mesmo que mais nada?

Se a leitora precisa fazer algo, dito na primeira frase, sem nenhum enquadramento antes disso. Uma leitora que encontra uma nota disparada por incidente muitas vezes já está preocupada, porque ouviu sobre o problema por uma página de status, um thread de suporte, ou seus próprios usuários, e uma nota que abre com contexto antes do item de ação lê como estar segurando informação exatamente nas circunstâncias em que segurar informação lê pior. "Nenhuma ação necessária, isso corrige uma vulnerabilidade que não exigia dados de usuário para ser explorada" e "Atualize imediatamente: esta release corrige um bug que podia mostrar dados de uma conta para outra" são ambas uma frase, e ambas fazem todo o trabalho que uma leitora ansiosa precisa antes de ler mais qualquer coisa.

A edição normal ainda se aplica quando não há tempo para fazê-la?

O instinto de comprimir sobrevive mesmo quando o processo de vários rascunhos que normalmente o produz não sobrevive. A reescrita descreve cortar um primeiro rascunho verboso até sua essência; sob pressão de tempo, muitas vezes não há primeiro rascunho para cortar, o que significa que a disciplina precisa operar na sua cabeça enquanto você escreve, em vez de como um passo separado depois. A abordagem mais rápida: escreva a frase que você diria em voz alta para alguém perguntando "o que preciso saber", e pare, porque essa frase costuma ser tanto a mais rápida de produzir quanto a única que uma leitora naquele estado vai de fato processar.

Release note normal	Release note de emergência
Escrita depois do code review, antes da publicação	Frequentemente escrita junto com a correção, antes de uma revisão completa
Otimizada para escaneamento rápido em muitas entradas	Otimizada para uma entrada lida isolada, sob estresse
Pode deixar detalhes para o changelog vinculado	Precisa colocar o fato mais importante primeiro
Enquadramento e contexto são bem-vindos	Enquadramento antes do item de ação lê como enrolação

Alguma vez está tudo bem publicar uma nota antes de estar realmente certa sobre a causa do problema?

Sim, se a nota for honesta sobre essa incerteza em vez de implicar uma certeza que você não tem. "Fizemos deploy de uma correção para o aumento na taxa de erro no checkout; ainda estamos confirmando a causa raiz e vamos atualizar esta nota" é defensável e compra tempo corretamente; uma nota afirmando uma causa específica que você na verdade não confirmou é o tipo de palpite que as pessoas vão te citar de volta depois se ele se provar errado. A disciplina importante aqui não é a velocidade do diagnóstico, mas nunca deixar a certeza da nota exceder a certeza real do time, porque uma afirmação técnica errada em uma nota de emergência prejudica mais a confiança do que uma ignorância admitida.

Confiante demais, não verificado:
"Fixed: a race condition in the payment webhook handler
caused duplicate charges."

Honesto sob pressão de tempo:
"Corrigido: alguns clientes foram cobrados duas vezes
por um único pedido. Interrompemos novas ocorrências e
reembolsamos as contas afetadas em 24 horas.
Investigando a causa raiz."

Uma nota de emergência deveria mencionar a causa do problema, ou só que ele foi corrigido?

Diga o que foi corrigido e o que a leitora deveria fazer; guarde a causa raiz para uma nota de acompanhamento, uma vez que ela seja de fato conhecida, não estimada. Uma leitora no meio de um incidente quer exatamente dois fatos, se isso está resolvido e se isso afeta a ela, e uma explicação de causa raiz, mesmo precisa, compete com esses dois fatos por atenção no pior momento possível para perdê-la. Um post-mortem, publicado separadamente uma vez que a investigação esteja completa, é onde a causa raiz pertence; misturar os dois documentos sob pressão de tempo produz uma nota que é escrita mais devagar e lida mais devagar, o oposto do que uma emergência precisa.

O problema de atualizações forçadas de apps mobile também se aplica aqui?

O mesmo princípio se aplica, só que ainda mais comprimido. Release notes para apps mobile cobre atualizações forçadas, onde a nota precisa declarar o motivo e o prazo antes de qualquer outra coisa porque a leitora já está irritada por não ter escolha; uma nota de emergência na web é geralmente opcional para a leitora no sentido de que ela escolhe se age com base nela, mas o mesmo instinto de "declarar a restrição primeiro" se aplica, só que por um motivo diferente: não irritação, urgência.

Como evitar que uma nota de emergência leia como uma confissão de culpa quando não deveria?

Descreva a correção e seu efeito, não o erro, e resista ao impulso de se desculpar em excesso, o que lê como enchimento para uma leitora que quer os dois fatos acima. "Encontramos e corrigimos um bug que afetava algumas exportações" declara o que aconteceu sem adicionar drama a isso; "Lamentamos profundamente por este problema sério que afetou nossos valiosos clientes" atrasa a informação útil por uma frase inteira para entregar um momento emocional que a leitora não pediu. Uma nota concisa e factual não é fria, é respeito pelo estado real da leitora, que sob pressão real é impaciência, não necessidade de conforto.

FAQ

Uma release note de emergência deveria passar pelo mesmo processo de revisão que uma normal? Uma versão mais leve, não nenhuma: uma revisora rápida checando que a nota não exagera certeza vale os poucos minutos que exige, porque o risco de uma afirmação técnica não revisada estar errada é maior justamente por ela ter sido escrita rápido.

Está tudo bem publicar uma nota de emergência sem link para mais detalhes? Só brevemente. Uma nota sem link é aceitável como a primeira coisa publicada; adicione um link para uma página de status ou nota de acompanhamento assim que qualquer uma das duas existir, porque uma leitora que quer mais que aquela única frase que você deu precisa de um lugar para ir, mesmo que esse lugar diga "mais detalhes em breve".

Uma nota de emergência deveria alguma vez ser pulada completamente, deixando a correção sair em silêncio? Só para problemas que nenhuma leitora poderia ter notado ou sido afetada por eles; se há alguma chance de uma leitora ter experimentado o problema, a nota é o que diz a ela que acabou, e o silêncio lê como se o problema ainda pudesse estar ativo.

Por quanto tempo uma nota de emergência deveria continuar fixada ou em destaque depois que o incidente é resolvido? Até a janela de ansiedade imediata fechar, geralmente um dia ou dois, e então ela pode se dobrar no changelog normal como qualquer outra entrada; uma nota que permanece fixada por semanas começa a ler como uma preocupação não resolvida em vez de uma resolvida.

Protobuf breaking changes: o que sobrevive no fio

Tue, 22 Sep 2026 00:00:00 GMT

Uma API REST muda quando a forma do JSON muda, e a maior parte dessa forma é visível na resposta que dá para ler no navegador. Uma API gRPC muda quando o arquivo .proto muda, e o formato binário no fio do Protocol Buffers tem suas próprias regras sobre o que um cliente aguenta, que não têm nada a ver com o que os nomes dos campos dizem. Duas mudanças que parecem igualmente pequenas no diff, renumerar um campo e adicionar um campo novo, caem em lados opostos da linha que breaking changes traça em geral: uma é invisível para todo cliente existente, a outra quebra todos eles de uma vez. Diferenciar breaking changes de protobuf das mudanças seguras significa ler as próprias regras do formato no fio, não adivinhar pela aparência da mudança em um diff de .proto.

Por que o número do campo importa mais que o nome dele no Protobuf?

Porque o formato no fio codifica campos por número, não por nome. O código gerado em cada linguagem lê e escreve esses números; o nome do campo email no seu arquivo .proto é uma conveniência humana que nunca toca nos bytes binários enviados pela rede. Renomear um campo, de email para email_address, é seguro no fio binário enquanto o número permanecer o mesmo, o que surpreende engenheiras acostumadas com REST, onde uma chave JSON renomeada é exatamente o tipo de mudança que quebra um cliente. A exceção é justamente o caso REST: os formatos ProtoJSON e texto serializam o nome, então uma renomeação quebra o transcoding JSON (um grpc-gateway, por exemplo), arquivos em formato texto e field masks. Renumerar o mesmo campo, mantendo o nome mas trocando 1 por 7, é o oposto: invisível em um code review que só mostra nomes, e quebra toda mensagem que o cliente enviar ou receber a partir daquele momento.

Mudança	Segura no fio	Por quê
Renomear campo, manter o número	Binário sim, JSON e texto não	A codificação binária usa o número; ProtoJSON e o formato texto usam o nome
Mudar o número do campo	Não	Toda mensagem existente agora é lida como um campo diferente
Adicionar campo novo com número novo	Sim	Clientes antigos ignoram campos que não conhecem
Remover um campo, reusar seu número antigo para outra coisa	Não	Dados antigos são decodificados no campo novo errado
Mudar o tipo de um campo de forma incompatível (ex: `int32` para `string`)	Não	A codificação no fio difere por tipo

Por que remover um campo é diferente de fazer o mesmo em uma resposta REST JSON?

Porque o número se torna radioativo. O próprio guia do Protobuf recomenda marcar o número de um campo apagado como reserved, em vez de permitir que seja reusado, porque é justamente no reúso que o dano real acontece: um cliente ainda rodando código gerado com meses de idade envia uma mensagem usando o número de campo antigo para um valor antigo, e o servidor, que agora espera que esse número signifique outra coisa, interpreta os dados errado silenciosamente em vez de rejeitá-los diretamente. REST não tem uma armadilha equivalente, porque uma chave JSON apagada simplesmente para de aparecer; não existe forma de uma requisição de um cliente antigo ser reinterpretada silenciosamente como outra coisa. Um arquivo .proto com reserved 4, 9, 12; no topo de uma mensagem é uma cicatriz permanente, e esse é o ponto: ele impede que aquele número acabe indo para um campo novo nas mãos de alguém que não conhece a história dele.

message Invoice {
  reserved 4; // era `legacy_customer_id`, removido em 2026-06-01
  reserved "legacy_customer_id"; // o nome também, para JSON/texto
  string customer_id = 5;
  string status = 6;
}

Adicionar um campo sequer precisa de uma entrada no changelog?

Geralmente não uma entrada de breaking change, mas frequentemente uma entrada comum, porque "seguro no fio" e "visível para uma leitora que se importa" são duas afirmações diferentes. Adicionar um campo a uma mensagem de resposta é estruturalmente de graça, clientes antigos decodificam a mensagem e ignoram automaticamente o campo novo. Mas quem está construindo uma integração nova contra esse serviço não tem como saber que o campo existe a menos que alguém diga, porque nem um build bem-sucedido nem um teste que passou tornam um novo campo opcional visível. Changelog de API cobre em geral o que uma entrada aditiva deve às leitoras; a razão específica do gRPC para escrevê-la mesmo assim é que não existe equivalente a olhar uma resposta REST em um debugger e notar uma chave nova aparecendo.

Como isso é diferente do que as chamadoras de GraphQL enfrentam?

As regras para adições coincidem, mas a exposição é diferente. Depreciação de esquema GraphQL cobre um modelo onde o cliente só recebe os campos que pede explicitamente, o que torna mudanças aditivas essencialmente sem risco e apenas remoções o perigo real. Clientes gRPC, em contraste, recebem tudo que o servidor envia e decodificam tudo contra sua própria cópia compilada do esquema; a exposição do cliente é limitada não pelo que ele pediu, mas apenas pelo que seu código gerado consegue ler. Essa diferença importa na hora de escrever o changelog: uma entrada GraphQL pode razoavelmente assumir que os clientes estão protegidos de campos que não pediram, uma entrada gRPC não pode assumir isso de forma alguma.

O versionamento de um serviço gRPC funciona igual ao `/v1/`, `/v2/` do REST?

A intenção é a mesma, o mecanismo é diferente. O que são v1 e v2 em uma API REST cobre versionamento como caminhos de URL paralelos servindo contratos diferentes; serviços gRPC geralmente são versionados através do nome do pacote dentro do próprio arquivo .proto, payments.v1.InvoiceService vira payments.v2.InvoiceService, o que muda o nome de serviço totalmente qualificado que o cliente disca em vez do segmento de URL que ele pede. As duas abordagens resolvem o mesmo problema, deixar o contrato antigo continuar funcionando enquanto o novo existe, mas um time com background REST muitas vezes procura o número de versão no lugar errado e não percebe que quem faz esse trabalho é a declaração do pacote.

O que uma entrada de changelog do gRPC deveria de fato nomear?

A mensagem, o número do campo, e se a mudança é aditiva ou uma remoção que exige migração, nessa ordem de importância para a leitora que decide se age ou não. "Adicionado shipping_address (campo 8) em Order" diz à integradora tudo que ela precisa para atualizar o código gerado e começar a usá-lo. "Reservado o campo 4 em Invoice, legacy_customer_id sumiu" diz a ela para verificar se algo na base de código dela ainda lê aquele campo, o que uma nota estilo REST "campo removido da resposta" não comunica com a mesma urgência, porque uma remoção REST só retorna menos dados, enquanto o reúso de campo do Protobuf os corrompe ativamente.

FAQ

O tipo de um campo pode alguma vez ser mudado sem quebrar o formato no fio? Só dentro de grupos de compatibilidade específicos que o Protobuf documenta, como estender int32 para int64 em alguns casos. Trate qualquer mudança de tipo como breaking a menos que você tenha verificado contra a própria tabela de compatibilidade do Protobuf; assumir compatibilidade por analogia com o sistema de tipos de uma linguagem é como isso dá errado.

A depreciação de campo no Protobuf funciona como a diretiva @deprecated do GraphQL? De forma parecida: o Protobuf suporta a opção de campo [deprecated = true], que ferramentas podem exibir. Nenhuma das duas é imposta: um servidor GraphQL continua respondendo a uma query por um campo depreciado, e um cliente protobuf continua codificando um. Ambas são indicativas e exigem o mesmo suporte de changelog.

Renumerar é seguro se você controla cada cliente? Em um sistema totalmente fechado, em princípio sim, mas isso remove toda a propriedade de segurança pela qual os números de campo existem, e "controlamos cada cliente" é uma afirmação que deixa de ser verdadeira no momento em que um build é cacheado, um deploy atrasa, ou um cliente que ninguém lembrava é adicionado. Reserve o número em vez de reusá-lo, mesmo internamente.

Serviços gRPC precisam de uma página de changelog como uma API REST pública? Só se times externos os consomem sem ler diffs de .proto diretamente, o mesmo teste de "quem está do outro lado" que changelog de API interna aplica em geral. Um serviço gRPC consumido só por outros serviços do mesmo time muitas vezes consegue passar sem um changelog formal em favor do histórico de commits, porque quem quer que o leia já tem o esquema aberto.

Formatos de arquivo de changelog: JSON, YAML ou só Markdown

Thu, 17 Sep 2026 00:00:00 GMT

A maioria dos times começa um changelog como arquivo Markdown porque é o caminho de menor resistência: legível no diff de um pull request, legível no GitHub sem renderizar nada, e familiar para qualquer um que já escreveu um README. Essa escolha funciona bem até algo além de uma pessoa precisar ler o arquivo, uma página, um widget, um resumo por email, e aí o formato para de ser de graça. Automação de changelog cobre a exigência estrutural em geral, um tipo, uma data, um corpo e um link; isso aqui é sobre qual formato de arquivo realmente entrega essa estrutura e quanto custa chegar lá com cada um.

O que há de errado com um changelog Markdown simples?

Nada, até algo precisar reparseá-lo de volta em campos. Um título, uma data e uma lista com marcadores embaixo é trivial de ler para uma pessoa e genuinamente difícil de parsear de forma confiável, porque Markdown não tem esquema: a data pode estar no título, em negrito na primeira linha, ou totalmente ausente em uma entrada antiga, e cada uma dessas variações é Markdown válido que uma pessoa lê corretamente e um parser não. Times que automatizam um changelog Markdown geralmente acabam escrevendo um parser caseiro baseado em regex que quebra na primeira vez que a formatação de uma entrada desvia mesmo que levemente, o que é frequente, porque nada força consistência na hora de escrever.

O que um formato estruturado realmente traz?

Uma garantia de que toda entrada tem a mesma forma, verificada quando a entrada é escrita em vez de adivinhada quando é lida. Um arquivo JSON ou YAML com um schema definido, tipo, data, versão, público, corpo, link, falha de forma barulhenta se um campo obrigatório está faltando, do mesmo jeito que uma resposta de API estrita faria; um arquivo Markdown simplesmente renderiza o que está lá, correto ou não. Essa diferença é invisível até o dia em que um script precisa da data de cada entrada para ordenar um feed, e metade das entradas tem isso em um lugar diferente.

# CHANGELOG.yml
- date: 2026-09-05
  type: breaking
  version: v2
  audience: api
  body: "POST /invoices now rejects a currency mismatch instead of silently converting."
  link: /blog/api-changelog/

Isso significa que o arquivo legível por humanos precisa sumir?

Não, e tentar fazer um arquivo YAML ou JSON servir dobrado como o que uma pessoa lê em um pull request costuma ser um erro na direção oposta: revisar um diff de JSON aninhado é pior do que revisar uma frase de prosa, e uma revisora que precisa parsear mentalmente uma estrutura de dados para pegar um erro de redação é uma revisora que eventualmente vai parar de pegar erros de redação. Os dois formatos podem coexistir: dados estruturados são a fonte de verdade que uma pipeline de automação lê, e uma renderização Markdown ou HTML gerada é o que uma pessoa realmente revisa e lê, produzida a partir do arquivo estruturado em vez de mantida manualmente ao lado.

Formato	Legível por humanos como está	Parseável por máquina sem código sob medida	Modo de falha comum
Markdown	Sim	Não	Forma inconsistente de entrada quebra parsers ingênuos
JSON	Ruim	Sim	Verboso; fácil de editar à mão para JSON inválido
YAML	Razoável	Sim	Sensível a espaço; uma indentação errada é um erro de parse silencioso, não barulhento

Qual formato estruturado é realmente mais fácil de editar à mão, JSON ou YAML?

YAML, para quem escreve entradas à mão em vez de por um gerador, porque elimina as aspas e o pareamento de chaves que JSON exige para cada string e objeto aninhado. O trade-off é que a sensibilidade do YAML a espaço falha silenciosamente de um jeito que os desencontros de chaves do JSON geralmente não fazem: um parser JSON rejeita de cara uma entrada malformada, enquanto um parser YAML pode aceitar um arquivo mal indentado e simplesmente parseá-lo na estrutura errada, o que é uma falha pior porque nada avisa que isso aconteceu. Se as entradas são sempre escritas só por um script, esse trade-off praticamente desaparece e o parsing mais estrito do JSON se torna a escolha padrão mais segura.

Uma página de changelog precisa do próprio formato estruturado, separado do arquivo que a alimenta?

Não um separado, o mesmo renderizado de forma diferente. Uma página de changelog cobre como tornar a própria página legível por máquina por meio de um feed JSON e marcação schema.org; esse feed é saída gerada, não uma segunda fonte de verdade a ser mantida sincronizada com o arquivo subjacente. Manter dados estruturados à mão em dois lugares, um arquivo fonte e o feed de uma página, é como os dois acabam divergindo, então a decisão de formato de arquivo tomada aqui deveria ser a única coisa da qual tudo a jusante, página, widget, email, é gerado, nunca copiado à mão.

Vale a pena o custo de migração de converter um changelog Markdown existente para um formato estruturado?

Geralmente só quando automação é o objetivo real, não antes. Um projeto de uma pessoa só publicando um arquivo Markdown em um README do GitHub não tem uma necessidade real de automação, e converter para YAML não compra nada além de cerimônia. A conversão se paga sozinha no momento em que mais de um consumidor a jusante, uma página, um email de resumo, um feed público, precisa ler os mesmos dados, porque esse é exatamente o ponto onde as inconsistências de um parser Markdown começam a produzir saída visivelmente errada em vez de só ser chata de manter.

FAQ

Um changelog Markdown pode ser tornado parseável sem trocar de formato completamente? Parcialmente, com frontmatter: um pequeno bloco YAML no topo de cada entrada (data, tipo, versão) ao lado de um corpo Markdown para a prosa. Isso consegue os campos estruturados de que um parser precisa sem forçar a entrada inteira em JSON ou YAML, e é um meio-termo razoável para um time ainda não pronto para uma migração completa.

O formato do arquivo importa para SEO ou para como uma página de changelog rankeia? Não diretamente. Buscadores leem a página renderizada, não o arquivo fonte, então o formato do arquivo é invisível para eles; o que importa para a própria página é se ela é legível por máquina por direito próprio, o que é uma questão separada do que a gera.

Toda entrada de changelog deveria passar pelo mesmo arquivo, ou tipos podem ser divididos entre vários arquivos? Um arquivo só é mais simples até o volume de entradas torná-lo incômodo de diferenciar ou revisar; dividir por ano ou por categoria é uma válvula de escape razoável assim que os diffs de um único arquivo ficam grandes demais para revisar com sensatez, mas isso adiciona um passo de merge antes de qualquer coisa a jusante conseguir ler "todas as entradas" como uma lista só.

Existe um formato padrão de arquivo de changelog, como existe um padrão para RSS? Não um amplamente adotado. Keep a Changelog propõe uma convenção Markdown, e várias ferramentas têm a própria; um changeset é um arquivo Markdown com frontmatter YAML que nomeia o pacote e o bump, que é o padrão de frontmatter descrito acima. Nenhum deles é um formato que outras ferramentas leem de cara do jeito que leitores de RSS entendem RSS universalmente.

Pedidos duplicados: mesclar sem perder a voz original

Thu, 17 Sep 2026 00:00:00 GMT

Três clientas pedem a mesma capacidade em três semanas diferentes, redigida de três jeitos diferentes, e um processo de triagem construído para pegar duplicatas faz o trabalho dele: agrupa elas, conta como um pedido só com três votos, e o backlog fica limpo. Essa é a parte fácil. Quais etiquetas valem a pena cobre agrupar por capacidade subjacente antes de triar por redação como o conserto mecânico para duplicatas; o que não cobre é o que acontece com as palavras em si quando três pedidos viram uma linha só, e essa perda geralmente é maior do que o problema de contagem de duplicatas que ela resolveu.

O que realmente se perde quando duplicatas são mescladas?

A redação específica que cada solicitante usou, que costuma ser mais informativa do que a contagem de votos na qual ela colapsa. Uma clienta pode pedir "uma forma de exportar resultados filtrados", outra "exportação CSV que respeite meus filtros salvos", e uma terceira "exportação que não inclua colunas ocultas". As três são o mesmo pedido subjacente, corretamente agrupado, mas cada redação carrega uma ênfase levemente diferente sobre o que importa para aquela pessoa, e uma mesclagem que mantém só a redação da primeira submissão descarta as outras duas por completo. A contagem sobrevive; a textura que ajudaria alguém a construir a versão certa da funcionalidade, não.

Por que a textura importa se a contagem de votos já diz que existe demanda?

Porque demanda e design são perguntas diferentes, e só a redação específica responde a segunda. Dez votos em "exportação" diz a um time que vale a pena construir a funcionalidade; não diz nada sobre se "exportação" significa CSV, PDF, um email agendado ou um endpoint de API, e uma mesclagem que descarta nove das dez submissões originais em favor da redação da primeira pode estreitar silenciosamente a especificação para o que quer que a primeira solicitante tenha pedido por acaso, mesmo que as outras nove quisessem algo sutilmente diferente. O que um pedido de funcionalidade deveria realmente registrar cobre exatamente essa lacuna do lado da recepção; mesclar duplicatas é onde ela reaparece depois da recepção, exatamente no ponto onde um time mais precisa do alcance do que foi realmente pedido.

Como é um processo de mesclagem que mantém a redação em vez de descartá-la?

Adicionar em vez de substituir. O item canônico mantém um título único para a visão do backlog, mas a redação original de cada submissão mesclada continua anexada a ele, seja como uma lista de citações ou como tickets de origem linkados, para que qualquer um que revise o item depois consiga ver o alcance real do que as pessoas pediram em vez do resumo de uma pessoa do time. Isso custa quase nada para construir, um campo no ticket em vez de um sistema novo, e é a diferença entre uma mesclagem que comprime informação e uma que só comprime a exibição dela.

Funcionalidade: Exportação CSV filtrada
Votos: 12
Pedidos mesclados:
  - "uma forma de exportar resultados filtrados" (acct_4421)
  - "exportação CSV que respeite meus filtros salvos" (acct_8832)
  - "exportação que não inclua colunas ocultas" (acct_1097)
  ...

Toda duplicata merece ser mesclada, ou existem correspondências falsas?

Algumas são correspondências falsas, e tratar "soa parecido" como "é o mesmo pedido" é seu próprio modo de falha. "Me deixem exportar meus dados" e "me deixem exportar só a visão filtrada" podem ser agrupados por uma correspondência de palavra-chave em "exportar" enquanto na verdade descrevem dois escopos diferentes da mesma capacidade geral; mesclar eles ou infla a contagem de votos para a coisa errada ou, pior, lança a versão mais estreita porque ela chegou primeiro por acaso. Uma passada humana sobre o agrupamento, mesmo rápida, pega isso antes de acumular; uma correspondência automática de similaridade sozinha vai mesclar demais por vocabulário e mesclar de menos por intenção.

Quando a checagem de duplicatas deveria realmente rodar, na recepção ou depois?

As duas, por razões diferentes. Checar na recepção pega o caso óbvio, um pedido novo que reafirma algo que já está aberto, antes que ele vire um item não rastreado com vida própria; uma busca por similaridade contra os pedidos abertos no momento do envio resolve a maioria desses casos sem ninguém do time envolvido. Uma segunda passada depois, num ritmo mais lento, pega o caso que a recepção não vê: dois pedidos que usaram uma linguagem diferente o suficiente para escapar de uma correspondência por palavra-chave ou embedding na hora, mas que, depois que o time já viu uma dúzia de variações, se revelam a mesma capacidade de fundo. Pular a segunda passada deixa quase-duplicatas espalhadas sob títulos separados indefinidamente, cada uma com a própria contagem pequena de votos que nunca soma o número que teria feito a funcionalidade ser construída.

A solicitante deveria saber que a submissão dela foi mesclada em um item existente?

Sim, e essa é a mesma disciplina de fechar o loop de feedback do cliente aplicada um passo antes do normal: uma solicitante que enviou algo e nunca mais ouve nada conclui que o pedido dela não foi a lugar nenhum, mesmo que tenha sido corretamente mesclado em um item com outros onze votos que acabou sendo lançado. Uma confirmação curta, "combinamos isso com um pedido existente que outras pessoas também fizeram", custa uma mensagem e evita que uma clienta reenvie o mesmo pedido a cada poucos meses porque não tem visibilidade se ele foi de fato rastreado alguma vez.

Mesclar muda quem recebe crédito quando a funcionalidade é lançada?

Deveria incluir todo mundo, não só quem enviou primeiro. Fechar o loop de feedback cobre avisar solicitantes quando o pedido delas é lançado; para um item mesclado isso significa cada conta anexada à mesclagem, não só aquela cuja redação virou o título canônico, porque do ponto de vista de cada solicitante ela pediu isso e foi lançado, não importa a redação de quem um processo de triagem por acaso manteve. Com o Changeloop, isso significa que o pull request nomeia cada issue vinculada (Fixes #142, fixes #187); uma issue que ele não nomeia não recebe comentário.

FAQ

Quanta redação vale a pena manter por pedido mesclado, uma citação ou um link completo do ticket? Uma citação curta geralmente basta para o caso comum, já que o propósito dela é deixar uma revisora ver o alcance das redações de relance; mantenham o link completo do ticket também quando o original tinha contexto extra significativo, como uma captura de tela ou uma descrição detalhada de fluxo de trabalho que uma citação de uma linha achataria.

Manter a redação de cada duplicata torna o backlog mais difícil de escanear? Não, se estiver recolhida por padrão. O título canônico é o que uma revisora escaneando rapidamente vê; a redação mesclada está a um clique ou uma expansão de distância, presente para quem faz pesquisa mais profunda mas sem sobrecarregar a visão de quem só está contando votos.

E se dois pedidos parecem idênticos mas acabam querendo coisas diferentes depois de construídos? Separem eles de novo assim que isso ficar claro, e tratem a mesclagem original como uma decisão razoável tomada com a informação disponível na época, não como um erro cuja repetição deve ser evitada. Um sistema de agrupamento que nunca desfaz mesclagens vai acabar tendo algumas mesclagens erradas permanentemente cozidas.

Existe um limite de votos a partir do qual um pedido mesclado deveria receber uma revisão humana da redação subjacente? Não um número fixo, mas qualquer pedido chegando perto de uma decisão de construção merece isso independente da contagem de votos, porque esse é o ponto onde a diferença entre "exportação" e "exportação como CSV com filtros salvos" para de ser uma nuance e começa a ser a especificação.

Mudanças de schema no GraphQL: depreciação sem versão

Thu, 17 Sep 2026 00:00:00 GMT

Uma API REST pode publicar /v2/ ao lado de /v1/ e deixar cada consumidor migrar no próprio ritmo. O GraphQL tem um schema em um endpoint, e todo client, o app mobile no build do ano passado e o dashboard interno lançado hoje de manhã, consulta o mesmo graph. Não existe uma URL para bifurcar. Depreciar um campo significa marcá-lo como depreciado no lugar, em um schema do qual todo mundo já depende, o que torna a disciplina diferente do REST mesmo que o problema de fundo, avisar quem consome que algo vai sumir, seja o mesmo que depreciação de API cobre em geral.

Como o GraphQL marca um campo como depreciado, se não há versão para incrementar?

Com a diretiva @deprecated, aplicada direto no campo:

type Product {
  price: Float @deprecated(reason: "Use priceV2 for multi-currency support.")
  priceV2: Money
}

O campo continua consultável. Ele não some, não retorna 404, não muda de comportamento; só carrega uma anotação legível por máquina que a maioria das ferramentas GraphQL, GraphiQL, Apollo Studio, linters de schema, vai mostrar para quem navegar pelo schema ou escrever uma query contra ele. Esse é todo o mecanismo. Não existe um endpoint de depreciação separado, nenhum header, nenhum documento acompanhante exigido pela spec, o que é ao mesmo tempo o atrativo e a armadilha: a diretiva é fácil de adicionar e fácil de ignorar, porque nada obriga um client a olhar para ela.

Alguém realmente vê o motivo da depreciação?

Só quem usa o schema diretamente, por introspecção ou um editor consciente do schema, e esse é um público menor do que os leitores comuns de um changelog de API. Um app mobile construído contra uma query há seis meses já assou aquela query no binário dele; ele vai continuar pedindo price e continuar recebendo resposta, depreciado ou não, até alguém reconstruir o app com o campo novo e lançar uma atualização. A diretiva diz para uma desenvolvedora escrevendo código novo não usar o campo antigo. Ela não faz nada pelo client que já está lançado e rodando.

Mecanismo	Quem alcança
Diretiva `@deprecated`	Desenvolvedoras navegando o schema ou escrevendo queries novas
Falhas de CI do linter de schema	O time dono do código do client, se ele rodar um
Uma entrada de changelog	Quem quer que a leia, incluindo um time client sem linter
Nada (o campo simplesmente funciona)	Um client já construído usando o campo antigo

Um campo depreciado deveria mesmo assim ganhar uma entrada de changelog?

Sim, e ela faz mais trabalho do que a diretiva sozinha, porque um changelog alcança gente que a diretiva não alcança: um time parceiro que consome o graph sem navegar o schema dele, um client construído contra uma cópia do schema cacheada há meses, qualquer um que só notaria lendo prosa. Changelog de API cobre em geral o que uma entrada deve a quem chama; uma entrada de GraphQL deve uma coisa que o REST raramente precisa explicitar, porque quem chama REST deduz isso do número de versão: se o campo antigo ainda funciona hoje, ainda funciona com um aviso, ou de fato parou de retornar dados. A diretiva sozinha não responde nada disso para uma leitora que nunca abriu o schema.

Quando é realmente seguro remover um campo do schema?

Só quando os logs de query mostram que ninguém mais pede por ele, o que é uma pergunta de uso, não de calendário. Um campo pode carregar @deprecated por um ano e ainda ser estrutural para um client que nunca foi reconstruído; removê-lo em um cronograma fixo, como um Sunset de REST costuma fazer, quebra esse client sem nenhum aviso sobre o qual ele possa agir, porque o GraphQL não dá a ele nada sobre o que agir além da diretiva que ele nunca leu. Registre o uso em nível de campo antes de se comprometer com uma data de remoção, e trate qualquer contagem de query diferente de zero como uma pausa, não uma contagem regressiva.

Adicionar um campo carrega o mesmo risco que em uma API REST?

Estruturalmente menor, porque um client GraphQL só recebe os campos que pede explicitamente. Adicionar priceV2 ao lado de price não pode quebrar uma query existente do jeito que adicionar um campo a uma resposta JSON REST pode quebrar um deserializador estrito, porque nada obriga o client a pedir o campo novo. Adicionar um valor a um enum já existente é a exceção que vale a pena nomear no mesmo fôlego: um client que testa exaustivamente cada valor do enum, o que linguagens fortemente tipadas incentivam, quebra no momento em que um valor novo chega, independentemente de alguma query tê-lo pedido ou não. A segurança só vale para campos e membros de union que o client escolhe usar; ela não vale para um conjunto fechado que o código do client enumera à mão.

O que uma entrada de changelog do GraphQL precisa que uma entrada REST não precisa?

A forma da query, não só o nome do campo, porque "o campo price está depreciado" está sem exatamente a parte que quem chama realmente precisa: quais tipos e quais queries tocam nele. Uma entrada útil nomeia o tipo, o campo, o campo substituto e, se você conseguir gerar, as queries reais em produção que ainda pedem a forma antiga. Essa última parte, amarrar o aviso de depreciação ao uso real, é o que quem chama REST ganha de graça dos logs do servidor em uma URL e quem chama GraphQL não ganha, porque toda query bate no mesmo endpoint não importa o que peça.

Alguma coisa além de um campo pode carregar a diretiva `@deprecated`?

Valores de enum, usando a mesma diretiva direto na definição do valor em vez da do campo:

enum ShippingMethod {
  STANDARD
  EXPRESS
  OVERNIGHT @deprecated(reason: "Use EXPRESS with priority: true instead.")
}

A spec define @deprecated para exatamente dois lugares, a definição de um campo ou um valor de enum, e nada além disso na versão estável; a depreciação em nível de argumento ou de input-field existe só em linguagem de draft mais recente, não no que a maioria dos servidores implementa hoje. Um valor de enum marcado assim continua sendo um valor legal que um servidor ainda pode retornar ou aceitar, a mesma promessa de não quebrar nada que um campo depreciado faz, o que é o que torna seguro lançar isso antes de de fato remover o valor.

FAQ

O GraphQL suporta algo como um header Sunset para um endpoint inteiro? Não, porque geralmente só existe um endpoint. O timing da depreciação vive em nível de campo, no texto de motivo da diretiva @deprecated e em qualquer changelog ou guia de migração que um time publique junto, não em um header de resposta que um client possa ler programaticamente.

Um campo depreciado pode ser removido e depois readicionado com um tipo diferente? Só como um nome de campo novo. Reintroduzir o mesmo nome de campo com um tipo mudado é exatamente a mudança que quebra algo que o ciclo de depreciação existe para evitar; dê ao substituto o próprio nome, como priceV2 faz, e deixe o antigo se extinguir completamente antes do nome ficar livre para reuso.

O texto de motivo do @deprecated deveria linkar para a entrada de changelog? Sim, quando as ferramentas de schema suportarem isso. O campo de motivo aceita uma string simples, e uma URL dentro dessa string é o caminho mais curto de uma desenvolvedora encarando a saída de introspecção até a explicação mais completa que uma entrada de changelog pode dar.

Uma mudança de schema do GraphQL é alguma vez compatível com versões anteriores de um jeito que o REST não é? Mudanças aditivas de campo, sim, pelo motivo acima: clients só recebem o que pedem. Novos valores de enum são a exceção, porque um client que enumera um conjunto fechado pode quebrar com um valor que não esperava. Remoções e mudanças de tipo são exatamente tão quebradoras quanto seus equivalentes REST.

Como escrever um guia de migração de API

Mon, 07 Sep 2026 00:00:00 GMT

Um guia de migração de API é o documento que transforma uma mudança incompatível em uma checklist em vez de uma interrupção: o que mudou, o que fazer a respeito, e até quando. Uma entrada de changelog pode nomear uma mudança incompatível em duas frases; um guia de migração é o que quem chama realmente abre quando essas duas frases dizem "isso quebra você" e ela precisa saber exatamente o que editar. Publicar a entrada sem o guia é como quem chama descobre uma mudança incompatível por um ticket de suporte em vez do documento escrito para evitar exatamente isso.

O que é um guia de migração de API?

Um documento passo a passo que leva quem chama da forma antiga de uma API para a nova, escrito para alguém com código para mudar, não para alguém que ainda está decidindo se adota a API. Essa distinção importa: um guia de migração assume uma integração existente e tráfego de produção existente, então precisa cobrir rollback, migração parcial, e como saber se a migração funcionou, nada disso necessário para um guia de primeira integração.

Documento	Assume	Responde
Guia de migração	Uma integração existente	Como saio da forma antiga para a nova?
Entrada de changelog	Nada, só que a leitora confere	O que mudou, e quando?
Referência da API	Nada, ou uma primeira integração	O que esse endpoint faz?
Aviso de depreciação	Uma integração usando o antigo	Quando isso para de funcionar?

Um guia de migração geralmente fica entre os dois últimos: um aviso de depreciação dispara um relógio, e o guia de migração é o que quem chama segue antes que esse relógio se esgote.

Quando uma mudança precisa de um guia de migração, não só de uma entrada de changelog?

Quando há mais de um passo entre o comportamento antigo e o novo, ou quando a mudança toca pontos de chamada suficientes para que quem chama se beneficie mais de um exemplo trabalhado do que de uma descrição. O que é uma mudança incompatível, e como lançá-la cobre o teste para saber se uma mudança é incompatível; se a resposta é sim, a segunda pergunta é se o conserto é uma edição de uma linha ou uma migração de verdade. Um campo renomeado, quem chama consegue lidar só com a entrada de changelog. Uma mudança em autenticação, paginação ou tratamento de erros quase sempre merece um guia, porque o código de substituição correto não é óbvio a partir de uma descrição de uma frase.

O que um guia de migração precisa conter?

Cinco coisas, e pular qualquer uma delas é como um guia vira uma página que quem chama lê uma vez e depois volta a tentativa e erro. O código antigo, mostrado como realmente apareceria em um projeto. O código novo, mostrado da mesma forma, não como uma descrição abstrata da diferença. O que quebra se nada mudar, dito claramente, porque "nada" é uma resposta válida e comum que quem chama ainda precisa ouvir explicitamente. Uma forma de verificar se a migração funcionou, como um campo de resposta ou um código de status para checar. E um cronograma: quando o comportamento antigo para de funcionar, e se ambas as formas ficam disponíveis nesse meio-tempo.

## Migrando campos de moeda de float para integer (v3.0.0)

Antes:
  { "amount": 19.99 }

Depois:
  { "amount": 1999 }  // menor unidade monetária (centavos)

O que muda: `amount` agora é um inteiro na menor unidade da moeda da
conta. Código que lê `amount` como float vai ler um valor 100x maior
demais a partir de 1º de outubro de 2026.

Verificar: depois da migração, uma cobrança de $19,99 deve ser lida
como `amount: 1999`, não como `amount: 19.99`.

Cronograma: v2 continua retornando floats até 15 de janeiro de 2027.
v3 retorna inteiros desde o lançamento. As duas versões estão ativas
agora.

Cada uma dessas cinco coisas responde a uma pergunta que quem chama teria que adivinhar ou perguntar ao suporte, e esse é exatamente o custo real que um guia de migração economiza.

Quem deveria escrevê-lo, e quando?

Quem projetou a mudança, no mesmo momento em que ela é lançada, não um time de suporte reconstruindo-o depois a partir de tickets. Quem tomou a decisão sabe em quais partes do comportamento antigo ninguém deveria ter confiado e quais eram um contrato acidental; um guia escrito depois por alguém sem esse contexto tende a explicar demais o óbvio ou a perder aquele um caso extremo que realmente quebra as pessoas. O guia e a entrada de changelog que anuncia a mudança incompatível deveriam sair juntos, com a entrada linkando para o guia em vez de repeti-lo.

Como isso se relaciona com versionamento e o changelog de API?

Diretamente: um guia de migração é a versão detalhada do que uma entrada MAJOR em semantic versioning e o seu changelog só resume em uma frase. A entrada de changelog diz que uma mudança é incompatível e a grandes traços o que mudou; o guia de migração é o link que essa entrada deveria carregar. Changelog de API: o que publicar e quem lê lista o guia de migração como um dos cinco documentos que uma API mantém, cada um respondendo a uma pergunta diferente; esse é o que responde "como eu realmente saio de A para B", e merece sua própria página justamente porque essa resposta costuma ser longa demais para uma entrada de changelog.

Por quanto tempo um guia de migração deveria ficar publicado?

Pelo menos enquanto o comportamento antigo continuar acessível, e idealmente depois também. Quem migra dezoito meses atrasada, depois de ignorar três avisos de depreciação, ainda precisa do guia, e apagá-lo no dia em que o comportamento antigo é desligado só garante que quem mais precisa dele não vai encontrá-lo. Mantenha-o em uma URL estável e atualize a seção de cronograma em vez de retirar a página. O próprio guia de upgrade da Stripe é um exemplo público do padrão: uma única página, mantida atualizada release após release, em vez de um documento novo por versão que fica desatualizado assim que a próxima sai. O guia de vocês merece um lugar igualmente fácil de achar, ao lado da documentação que quem chama já está lendo, em vez de enterrado em um arquivo de blog.

FAQ

Toda mudança incompatível precisa de um guia de migração? Não. Uma mudança que quem chama consegue resolver só com a entrada de changelog, como um único campo renomeado com uma substituição óbvia, não precisa de um guia separado. Uma mudança que toca vários pontos de chamada ou precisa de um exemplo trabalhado, precisa.

Um guia de migração deveria ficar com a documentação da API ou no changelog? Com a documentação, linkado da entrada de changelog. A entrada é o que uma assinante vê primeiro; o guia é o que ela precisa assim que decide agir, e pertence ao lado do material de referência que quem chama já está usando.

Qual é a diferença entre um guia de migração e um aviso de depreciação? Um aviso de depreciação declara que algo vai desaparecer e até quando. Um guia de migração são as instruções sobre o que fazer a respeito. Um aviso de depreciação sem guia de migração linkado dá a quem chama um prazo sem dizer como cumpri-lo.

O comportamento antigo e o novo deveriam ser documentados juntos durante uma janela de migração? Sim, na mesma página se possível, para que quem chama veja exatamente o que mudou em vez de montar isso a partir de dois documentos separados escritos em momentos diferentes.

Um check de changelog para o GitHub Actions

Mon, 07 Sep 2026 00:00:00 GMT

Todo time que mantém um changelog manualmente já teve a mesma conversa depois do mesmo incidente: um release saiu sem entrada, alguém pergunta por quê, e a resposta honesta é que a pessoa que a teria escrito estava correndo e o passo do changelog só existia na memória. Automação de changelog cobre o que um pipeline pode automatizar com segurança e o que ainda precisa de uma pessoa; um check de changelog no CI é a outra metade desse problema, porque automatizar a escrita não ajuda se ninguém é obrigado a acioná-la em primeiro lugar. O GitHub Actions é onde a maioria dos times já roda os checks dos pull requests, então é lá que este também vive.

Por que "pedimos para as pessoas adicionarem uma entrada" falha num padrão previsível?

Porque isso compete por atenção com tudo mais em um pull request, e é a única parte sem consequência imediata ao pular. Testes falham alto e bloqueiam o merge. Uma entrada de changelog faltando não bloqueia nada, então perde assim que alguém está com pressa, o que na prática é a maior parte do tempo. Uma política imposta pela memória se degrada exatamente no ritmo que se esperaria: bem nas primeiras semanas depois de todo mundo concordar, depois abandonada em silêncio assim que a pessoa que se importava sai de férias ou muda de time.

O que um check de CI para uma entrada de changelog realmente verifica?

Não a qualidade da escrita, só que a entrada existe e está bem formada, o que é o escopo certo para um check de changelog que roda no CI em vez de na cabeça de uma pessoa. Uma forma comum: o check olha o diff do PR e exige ou um arquivo novo em um diretório de changesets (o padrão que Changesets e ferramentas parecidas usam) ou uma linha modificada em um arquivo de changelog, e falha o build se nenhum dos dois existir. A revisão do que a entrada realmente diz continua acontecendo onde sempre aconteceu, no code review, porque esse julgamento não pertence a um script.

O que o check de CI verifica	O que ele não verifica
Existe um changeset ou linha de changelog no diff	Se a redação está clara
A entrada referencia o pacote certo, em um monorepo	Se a mudança sequer merece uma entrada
O arquivo é sintaticamente válido (frontmatter, forma JSON)	Se a entrada é honesta sobre o impacto

Todo PR precisa de uma, ou algumas mudanças são isentas?

Algumas são isentas, e a lista de isenções é onde esses sistemas realmente se constroem ou são abandonados. Um bump de dependência sem efeito visível, uma mudança só de testes, um refactor interno sem mudança de comportamento: nenhum desses deveria forçar quem contribui a inventar uma entrada de changelog para algo que não importa para ninguém que lê o changelog. O padrão que funciona é uma etiqueta ou flag que quem contribui pode aplicar (no-changelog-needed) e que satisfaz o check de CI sem arquivo, revisada por quem aprova o PR, para que a própria isenção passe pelo mesmo escrutínio que uma entrada passaria.

O que acontece com exceções legítimas, como um hotfix urgente?

O gate pertence ao merge, não ao deploy: um hotfix sob pressão real de tempo pode mergear com uma entrada provisória ou um ticket de acompanhamento, desde que o check de CI seja satisfeito pela intenção em vez de só um parágrafo terminado; alguns times aceitam um stub de uma linha que uma mantenedora aprimora antes do próximo corte de release. O que o gate nunca deveria permitir é pular o passo em silêncio, porque um stub esquecido é uma falha menor do que uma entrada que nunca existiu, e um stub pelo menos deixa um rastro que alguém pode encontrar depois.

# .github/workflows/changelog-check.yml
on:
  pull_request:
    types: [opened, synchronize, reopened, labeled, unlabeled]
jobs:
  changelog:
    if: >-
      !contains(github.event.pull_request.labels.*.name,
      'no-changelog-needed')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0 # the diff needs the base branch
      - name: Require changelog entry
        run: |
          base="origin/${{ github.base_ref }}"
          if ! git diff --name-only "$base"...HEAD \
              | grep -q '^\.changeset/'; then
            echo "No changeset. Add one, or have a maintainer"
            echo "apply the no-changelog-needed label."
            exit 1
          fi

Como vocês sabem que o check em si está correto antes que ele comece a bloquear PRs de verdade?

Abram primeiro um pull request de teste contra uma branch descartável: um com changeset, um sem, e um carregando a etiqueta de isenção, e confirmem que os três dão o resultado esperado antes que o check passe a valer para o trabalho de qualquer outra pessoa. Um check de changelog que falha aberto, aprovando todo PR porque uma condição foi escrita ao contrário, é pior do que não ter check nenhum, porque parece cobertura que não existe. Um workflow_dispatch no mesmo arquivo, rodado manualmente contra alguns PRs recentes já mergeados, pega a maioria desses erros sem precisar de um pull request ao vivo.

A mesma ideia funciona fora do GitHub Actions?

A forma se mantém, só a sintaxe muda. O GitLab CI expressa a mesma regra como um bloco rules de job checando $CI_MERGE_REQUEST_LABELS em vez de um if do GitHub Actions, e uma aprovação obrigatória de merge request pode substituir o passo de revisão da isenção. O check que este artigo descreve é do GitHub Actions porque é a plataforma em que a maioria de quem está lendo já está, mas a exigência de fundo, um gate verificado por máquina em vez de uma convenção pedida, é a mesma em qualquer lugar onde o CI roda antes de um merge.

Isso funciona do mesmo jeito em um monorepo?

Precisa de mais uma peça: para qual pacote é a entrada. Changelogs de monorepo cobre por que um único arquivo para o repositório inteiro para de funcionar assim que os pacotes são lançados independentemente; o check de CI herda a mesma exigência; um changeset que não nomeia um pacote não é uma evidência útil de que o changelog certo vai atualizar, só que algum arquivo mudou em algum lugar do diff. Ferramentas construídas para isso (Changesets é a comum no ecossistema JavaScript) pedem para quem contribui escolher o pacote afetado e um bump de semver no mesmo momento em que o changeset é criado, então o check de CI ganha as duas peças de graça em vez de inferir depois.

FAQ

O check de CI deveria bloquear o merge, ou só avisar? Bloquear. Um aviso é funcionalmente idêntico a pedir educadamente, o que já falhou. A etiqueta de isenção existe exatamente para que um caso genuíno de só-aviso ainda tenha um caminho legítimo pelo mesmo gate rígido.

Quem revisa se uma etiqueta de isenção foi aplicada corretamente? Quem quer que aprove o pull request, como parte da revisão que já está fazendo de qualquer forma. A etiqueta nunca deveria ser autoaplicada e não revisada, ou ela vira a mesma brecha silenciosa que o gate deveria fechar.

Exigir isso em CI substitui a necessidade de um pipeline de automação de changelog? Não, alimenta um. Automação de changelog cobre transformar entradas estruturadas em uma página, um feed e um e-mail; o check de CI é o que garante que essas entradas estruturadas existam para serem automatizadas em primeiro lugar.

Qual é a menor versão disso que vale a pena construir primeiro? Um único check que falha se nenhum arquivo mudou embaixo de um diretório de changelog designado, com uma etiqueta de isenção. Roteamento por pacote e inferência de semver para um monorepo podem vir depois; o hábito central, uma entrada existe ou alguém disse explicitamente que não é necessária, é o que vale a pena ter desde o primeiro dia.

Recusar um pedido de funcionalidade sem perder a cliente

Mon, 07 Sep 2026 00:00:00 GMT

Fechar o ciclo geralmente significa dizer a alguém que o pedido dela foi lançado. A metade difícil, para a qual a maioria dos sistemas de rastreamento não tem processo nenhum, é dizer não. A maioria dos pedidos de funcionalidades nunca é lançada, o que significa que a maior parte do fechamento de ciclo que um produto realmente deve às suas usuárias é uma recusa, não um anúncio, e uma recusa mal conduzida custa mais boa vontade do que o silêncio teria custado. Bem conduzida, pode custar quase nada, porque o que quem pediu mais quer, na maioria das vezes, é saber que foi ouvida, não a funcionalidade em si.

Por que recusar bem importa tanto quanto lançar bem?

Porque o silêncio se lê como uma recusa sem explicação, e um não explicado se lê como atenção. Quem não ouve nada presume que o pedido foi ignorado ou perdido, e as duas conclusões ensinam a ela a parar de se dar ao trabalho de perguntar, o que é o mesmo resultado que um produto tem com uma recusa de verdade, só que alcançado mais devagar e com mais ressentimento pelo caminho. Uma resposta que diz não, claramente e com um motivo, fecha o ciclo tão completamente quanto uma funcionalidade lançada, e faz isso mais rápido.

Resposta	O que quem pediu aprende	Custo para a relação
Silêncio	Ninguém leu, ou ninguém se importa	Alto, e se acumula a cada pedido futuro
Resposta automática sem motivo	Está em alguma fila, por tempo indefinido	Médio; compra tempo mas não confiança
Recusa com motivo	Foi lida, considerada e respondida	Baixo, se o motivo for honesto
Recusa com alternativa	A necessidade real foi realmente ouvida	O mais baixo; geralmente constrói confiança

O que faz uma recusa cair mal?

Quase sempre três coisas, combinadas. Genericidade: um "obrigada pelo feedback" pronto que não menciona o que realmente foi pedido se lê como se nem tivesse sido lido, mesmo que tenha sido. Atraso: uma recusa que chega seis meses depois do pedido, quando quem pediu já esqueceu que perguntou, parece pior que um não rápido, porque sugere que o pedido ficou parado em vez de considerado e recusado. E um motivo que não se sustenta: "não está no nosso roadmap" não responde nada, enquanto "isso exigiria redesenhar como as permissões funcionam, o que não planejamos mexer esse ano" dá a quem pediu algo que ela realmente pode avaliar e, se importar o suficiente, escalar ou contornar.

O que uma boa recusa deveria realmente dizer?

Quatro coisas, nesta ordem: um reconhecimento que nomeia o pedido específico, não uma paráfrase genérica; o motivo real, declarado honestamente mesmo quando o motivo honesto é "isso não se encaixa para onde o produto está indo" em vez de uma desculpa mais suave; se a porta está fechada ou só não está aberta agora, porque isso exige tons bem diferentes; e, quando existe, uma alternativa que atende à necessidade subjacente mesmo que não seja a funcionalidade pedida ao pé da letra.

Oi Jamie,

Obrigada pelo pedido de adicionar importação em massa de CSV para
convites de time. Avaliamos, e não vamos construir isso: nosso fluxo
de convite é construído em torno da revisão individual de cada novo
membro por motivos de segurança, e importação em massa iria contra
isso por design, não por descuido.

Se o problema real é convidar um time grande rapidamente, a API
suporta convites individuais via script, o que dá quase toda a
velocidade sem pular a revisão: [link]. Me avise se quiser ajuda para
configurar isso.

Repare o que isso faz que um template não consegue: nomeia a funcionalidade real, dá um motivo ligado a uma decisão de design de verdade em vez de uma política vaga, e oferece um caminho que resolve o problema subjacente em vez de só fechar o ticket.

Como isso difere de fechar o ciclo em uma funcionalidade lançada?

A mecânica é parecida, o tom não. Fechando o ciclo de feedback com o cliente cobre o caso lançado, onde a mensagem é boa notícia e o risco principal é esquecer de enviá-la. Uma recusa é má notícia, ou pelo menos notícia indesejada, e precisa de mais cuidado no motivo dado e menos automação na entrega: uma notificação de funcionalidade lançada pode ser um comentário de template disparado por uma mudança de status, mas uma recusa que se lê como template é exatamente a falha que essa abordagem inteira tenta evitar. Os dois compartilham uma exigência, porém: o pedido original tem que continuar ligado a quem o fez, a mesma disciplina de rastreamento que rastreamento de pedidos de funcionalidades cobre, senão não há como enviar nenhuma das duas mensagens individualmente.

Uma recusa deveria ser pública, como um status em um roadmap público?

Geralmente não o motivo específico, embora o status possa ser. Roadmap público cobre etiquetas de status que quem pediu pode conferir sem perguntar de novo, e um status "recusado" ou "não planejado" pode fazer parte desse sistema. Mas o motivo detalhado, especialmente quando toca prioridades internas ou contexto pouco lisonjeiro, geralmente vale mais na resposta individual do que em uma página de status pública, onde a mesma redação precisa funcionar para cada leitora em vez da única pessoa que realmente perguntou.

Todo pedido recusado merece uma resposta individual?

Todo pedido de uma pessoa nomeada e alcançável sim, pelo menos uma curta. Pedidos de alto volume, duplicados ou anônimos são a exceção: agrupar pedidos semelhantes e responder uma vez por grupo, ou atualizar uma etiqueta de status compartilhada, é razoável quando respostas individuais realmente não escalam. A linha a manter é que "não podemos responder a todo mundo individualmente" deveria ser uma restrição operacional real, verificada contra o volume real, não uma desculpa padrão para pular uma resposta que teria levado dois minutos.

FAQ

É melhor recusar rápido com um motivo fraco, ou tirar um tempo para um bom? Rápido, com um motivo honesto, vence os dois separados. Uma resposta rápida com um motivo real, mesmo curto, supera uma resposta lenta com uma polida; o próprio atraso é parte do que danifica a confiança.

Uma recusa deveria algum dia prometer reconsiderar o pedido depois? Só se isso for realmente provável e existir um mecanismo para realmente reconsiderá-lo, como uma etiqueta que o traz de volta em um ciclo de planejamento. Um vago "vamos manter em mente" sem tal mecanismo é funcionalmente o mesmo que silêncio, só formulado com mais gentileza.

E se o motivo honesto for algo que a empresa não pode compartilhar, como uma preocupação competitiva? Diga isso diretamente em vez de inventar um motivo mais suave. "Não podemos compartilhar o raciocínio específico aqui, mas isso não é algo que planejamos construir" é mais honesto, e mais respeitado, do que uma explicação inventada que desmorona diante de uma pergunta de acompanhamento.

Recusar um pedido significa que ele deveria ser apagado do rastreamento? Não. Mantenha-o, etiquetado como recusado com o motivo, para que faça parte do padrão contra o qual o próximo pedido semelhante é agrupado, e para que um contexto mudado depois (uma nova integração, uma nova prioridade de time) possa trazê-lo de volta em vez de começar a avaliação do zero.

Release notes de feature flag: o que dizer, e quando

Mon, 07 Sep 2026 00:00:00 GMT

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.

Tickets de suporte vs. pedidos: em que confiar?

Mon, 07 Sep 2026 00:00:00 GMT

Um quadro de pedidos de funcionalidades captura o que usuárias pedem quando têm tempo de sentar e descrever o que querem. Um ticket de suporte captura onde usuárias estão travadas agora mesmo, frequentemente irritadas, frequentemente sem o vocabulário para descrever de forma limpa o pedido subjacente. Os dois são sinal real, e equipes que olham só para um dos dois acabam resolvendo com confiança o problema errado, porque cada canal super-representa sistematicamente um tipo diferente de usuária e um tipo diferente de necessidade. Priorizando pedidos de funcionalidades cobre classificar o que já está no quadro; isto é sobre a lacuna entre o que chega ao quadro e o que só aparece como ticket de suporte.

Por que o mesmo problema subjacente apareceria em um canal e não no outro?

Porque os dois canais têm custos de ativação diferentes, e o tamanho desse custo decide quem o supera. Registrar um pedido de funcionalidade exige iniciativa: uma usuária precisa acreditar que o pedido vale a pena articular, achar o quadro, e escrever algo coerente, o que seleciona usuárias engajadas e pacientes já investidas no produto. Registrar um ticket de suporte exige quase nenhuma iniciativa em comparação, frequentemente só um clique em "ajuda" no meio de uma tarefa, o que significa que captura usuárias frustradas no momento, incluindo aquelas que nunca se dariam ao trabalho com um quadro de pedidos. Uma lacuna real no produto pode ser invisível no quadro de funcionalidades e barulhenta no suporte simplesmente porque as usuárias que a encontram são as menos propensas a registrar um pedido formal.

O volume de tickets para uma funcionalidade ausente significa a mesma coisa que a contagem de votos para ela?

Não, porque medem populações diferentes sob condições diferentes. Um pedido de funcionalidade com cem votos representa cem pessoas que tiraram tempo para achar e apoiar um pedido existente, o que é um sinal forte de demanda durável e ponderada. Cem tickets de suporte sobre a mesma lacuna subjacente, registrados no mesmo período, provavelmente representam usuárias esbarrando em uma parede no momento, algumas das quais esqueceriam completamente assim que a fricção imediata passasse. Tratar os dois como sinal equivalente de "cem pessoas querem isso" superpondera o volume de tickets, porque tickets são baratos de gerar e votos não.

Quadro de pedidos de funcionalidades	Tickets de suporte
Exige iniciativa para registrar	Exige quase nenhuma
Captura demanda ponderada e durável	Captura frustração no momento
Inclina para usuárias engajadas e pacientes	Captura usuárias que nunca usariam o quadro
Uma contagem de votos é sinal real de compromisso	Uma contagem de tickets reflete fricção, nem sempre desejo

O que significa quando uma funcionalidade tem tickets de suporte mas quase nenhum voto no quadro?

Frequentemente, que o pedido existe mas as usuárias que o encontram não sabem que o quadro existe, não acreditam que votar mudaria algo, ou encontram o problema raro demais para se dar ao trabalho de trocar de canal para registrá-lo formalmente. Essa é exatamente a população que um quadro de pedidos perde estruturalmente, e uma contagem baixa de votos aqui é prova de uma lacuna de medição, não de demanda baixa. Tratem um cluster de tickets de suporte em torno de uma funcionalidade ausente como o próprio sinal que vocês mesmos registram no quadro em nome das usuárias, em vez de desconfiar dos tickets, para que não fique invisível para quem prioriza só a partir de contagens de votos.

Quadro se lê como baixa prioridade:
"Export to CSV": 4 votos em 6 meses

Suporte conta uma história diferente:
"Export to CSV": 31 tickets no mesmo período, cada um
de uma conta diferente, cada um fechado com "não
suportado no momento, vamos repassar o feedback"

Um pico de tickets de suporte sempre significa que o problema subjacente é uma funcionalidade ausente?

Não, e é aqui que os dois canais podem enganar na direção oposta. Um pico de tickets é tão frequentemente causado por uma interface confusa em torno de uma funcionalidade já existente, um bug, ou uma mudança que saiu sem explicação adequada, nada disso resolvido construindo algo novo. Ler cada pico de tickets como "usuárias querem uma funcionalidade que não temos" produz um roadmap cheio de coisas que na verdade eram lacunas de documentação ou problemas de usabilidade disfarçados. O ticket de suporte diz onde está a fricção; não diz sozinho se a solução é uma funcionalidade nova, uma mudança de interface, ou um artigo de ajuda melhor, e confundir isso desperdiça tempo de engenharia na solução errada.

Como os dois sinais deveriam realmente ser combinados ao decidir o que construir?

Usem tickets para achar onde está a fricção, e usem o quadro de pedidos, mais contato direto onde o quadro está fraco, para confirmar como o resultado realmente desejado se parece. Um cluster de tickets identifica um problema real, sentido; raramente especifica a solução com precisão suficiente para construir contra ela, porque uma usuária frustrada em uma conversa de suporte descreve sintomas, não especificações. O quadro de pedidos, quando tem votos suficientes sobre o mesmo problema subjacente, tende a carregar mais do detalhe de "o que realmente satisfaria isso", porque escrever um pedido já é um ato de especificar o que se quer, não só relatar o que está errado.

Agentes de suporte deveriam registrar tickets como pedidos de funcionalidades eles mesmos?

Sim, e essa é a correção de maior alavancagem para a lacuna entre os dois canais. Uma agente que reconhece um ticket como um pedido de funcionalidade disfarçado, em vez de simplesmente resolvê-lo e seguir em frente, pode registrá-lo no quadro em nome da cliente, o que fecha diretamente a lacuna de medição em vez de exigir que a cliente descubra e use um segundo canal. Isso só funciona se registrar levar segundos, não minutos, para a agente, para que a fricção de fazer isso seja menor que a fricção de simplesmente fechar o ticket e passar para o próximo.

FAQ

Votos de pedidos de funcionalidades deveriam alguma vez ser descontados se todos vêm de uma única conta ou equipe? Sim, ponderem por contas ou organizações distintas em vez de contagem bruta de votos, porque cinco votos de cinco pessoas na mesma empresa representam as prioridades de uma única cliente, não cinco confirmações independentes de demanda.

Vale a pena construir uma funcionalidade que aparece muito em tickets mas tem quase nenhum voto? Frequentemente sim, desde que o volume de tickets venha genuinamente de contas distintas e a necessidade subjacente esteja confirmada em vez de assumida; tratem a contagem baixa de votos como um artefato de medição do custo de ativação do quadro, não como prova de que a demanda não é real.

Como distinguir de relance um ticket de confusão de interface de um ticket genuíno de funcionalidade ausente? Vejam se a resolução envolve explicar uma capacidade existente ou pedir desculpas por uma ausente. Um padrão de resoluções "ah, na verdade está bem ali" aponta para um problema de interface ou descobribilidade; um padrão de "ainda não suportamos isso" aponta para uma lacuna real.

Essa distinção importa tanto assim com um volume de suporte muito pequeno? Menos mecanicamente, já que um punhado de tickets é fácil de ler individualmente sem precisar de análise agregada, mas o viés subjacente, tickets super-representam usuárias frustradas e sub-representam as pacientes, está presente em qualquer escala e vale a pena ter em mente mesmo quando vocês leem cada ticket sozinhas.

Como rastrear pedidos de funcionalidades sem perdê-los

Mon, 07 Sep 2026 00:00:00 GMT

O rastreamento de pedidos de funcionalidades falha quase sempre de uma de duas formas. Ou os pedidos não têm para onde ir, então vivem em caixas de entrada e threads do Slack onde são esquecidos um por um, ou têm um lugar para ir que ninguém revisita, então são esquecidos todos de uma vez. Um sistema que funciona precisa resistir às duas falhas: precisa de um único lugar onde cada pedido pousa, e de um motivo para abrir esse lugar de novo no mês que vem.

De onde os pedidos de funcionalidades realmente vêm?

De mais canais do que a maioria dos sistemas de rastreamento contempla. Um ticket de suporte que inclui um "seria legal se". Um comentário em um roadmap público. Uma ligação de vendas em que uma cliente em potencial nomeia a única coisa que está bloqueando o negócio. Um widget dentro do produto. Cada canal tem sua própria dona e suas próprias ferramentas, e é exatamente por isso que os pedidos se espalham: a fila de tickets de suporte e o backlog do time de produto raramente são o mesmo sistema, e um pedido que chega a apenas um dos dois, na prática, só chegou a um departamento.

Origem	Dona típica	Onde mais costuma sumir
Tickets de suporte	Time de suporte	Fechado como resolvido, nunca mais revisitado
Ligações de vendas	Vendas / gestão de contas	Um campo do CRM que ninguém no produto lê
Widget no produto	Produto	Um formulário enviado sem follow-up
Comentários no roadmap	Quem quer que tenha construído o roadmap	A própria thread de comentários
Redes sociais / reviews	Marketing ou ninguém	Capturado uma vez em print, depois some

Um único formulário de entrada para cada canal não funciona, porque ninguém vai adotá-lo. O que funciona é um destino para onde cada canal converge, mesmo que o roteamento no início sejam cinco minutos por dia de copiar e colar até ser automatizado.

O que realmente quebra o rastreamento de pedidos de funcionalidades?

Quase sempre duas coisas. A primeira é a falta de um destino: os pedidos recebem resposta no canal em que chegaram e nunca são registrados de forma durável em lugar nenhum, então o mesmo pedido vindo de três clientes diferentes parece três respostas isoladas e sem relação, em vez de um único sinal. A segunda, mais comum, é um destino que enche e para de ser lido. Uma planilha com 400 linhas sem filtro não é mais um sistema de rastreamento; é um arquivo que por acaso pode ser editado.

A segunda falha é a mais perigosa, porque parece que o rastreamento está funcionando. Os pedidos são registrados. Nada parece quebrado até alguém perguntar "quantas pessoas pediram X" e a resposta honesta ser "teríamos que ler todas as 400 linhas para saber".

O que um pedido de funcionalidade deveria realmente registrar?

O suficiente para responder três perguntas depois sem reler a mensagem original: o que foi pedido, se possível nas próprias palavras de quem pediu; quem pediu, e como contatá-la se a resposta acabar sendo "nós construímos"; e o que seria preciso para saber se é um pedido comum ou um caso isolado. Uma citação literal vale mais que uma paráfrase, porque uma paráfrase escrita por quem triou o pedido já carrega sua própria leitura, e é exatamente essa leitura que uma segunda pessoa não consegue verificar seis meses depois.

Quais etiquetas valem a pena?

Duas, e respondem perguntas diferentes. Uma etiqueta de tipo separa um pedido de funcionalidade de um relatório de bug, porque os dois precisam de donas e prazos diferentes, e misturá-los em uma única fila deixa as reclamações mais barulhentas passarem na frente dos pedidos. Uma etiqueta de prioridade, mantida em um conjunto pequeno como low, medium e high, separa "está bloqueando alguém de usar o produto" de "seria legal ter", porque as duas merecem tempos de resposta bem diferentes e nenhuma deveria herdar o ritmo da outra. Colocar certo a etiqueta de tipo assume que o pedido é o que ele diz ser; quando um pedido de funcionalidade é na verdade um bug cobre o caso em que as próprias palavras de uma cliente apontam essa etiqueta na direção errada.

A triagem automatizada pode aplicar as duas no momento em que o pedido chega. No changeloop, um envio pelo widget recebe a etiqueta feature-request ou bug e uma etiqueta priority:low|medium|high no mesmo passo, mais uma tag from-widget para que a origem fique visível sem abrir o item. Isso já basta para filtrar o backlog em um minuto em vez de uma tarde: me mostre cada pedido de funcionalidade de alta prioridade vindo do widget este mês.

Uma terceira etiqueta vale a pena assim que existe um roadmap público: um status que quem pediu consegue conferir sozinha. Roadmap público cobre por completo os status planned, building e shipped; resumindo, essa etiqueta transforma uma fila privada em algo que quem pediu pode consultar sem perguntar de novo.

Como se decide o que construir a seguir?

Agrupe antes de contar. Dez pedidos formulados de formas diferentes para a mesma capacidade subjacente se leem como dez linhas espalhadas em uma planilha, e como um sinal forte assim que agrupados, e esse agrupamento geralmente é o passo que falta, não a contagem. Um número bruto sem agrupamento tende a premiar a funcionalidade com o nome mais chamativo, não a que tem a maior demanda real por trás.

Pese por quem pede, não só por quantos pedem. Um pedido vindo de uma conta perto da renovação carrega uma urgência diferente do mesmo pedido vindo de um cadastro de teste, e um sistema de rastreamento que descarta esse contexto em favor de uma contagem nua está otimizando pelo número mais fácil de calcular, não pelo mais útil.

Cada decisão aqui também produz pedidos que perdem, e eles também merecem uma resposta; como recusar um pedido de funcionalidade cobre o que dizer a quem fez um pedido que não vingou. Agrupar e ponderar é só metade de "o que construir a seguir"; priorizar pedidos de funcionalidades cobre os frameworks de verdade, RICE, ponderação por receita e contagens brutas, e onde cada um falha.

Como se fecha o ciclo quando algo é lançado?

Esse é o passo que os sistemas de rastreamento mais deixam passar, e o que quem pediu realmente percebe. Fechando o ciclo de feedback com o cliente cobre a mecânica por completo; o que se aplica aqui é que fechar o ciclo só funciona se o pedido original continuar ligado a quem o fez. Um template de pedido de funcionalidade construído a partir de uma issue do GitHub, com a identidade de quem pediu presa à issue em vez de enterrada em um comentário, é o que torna possível uma notificação automática de "lançado" em vez de uma que alguém precisa se lembrar de enviar. Template de pedido de funcionalidade mostra o template concreto e para que serve cada campo.

FAQ

Qual ferramenta devo usar para rastrear pedidos de funcionalidades? O que o time já confere diariamente vence qualquer ferramenta dedicada que ninguém abre. Um tracker de issues do GitHub funciona bem se a engenharia já vive lá; um quadro leve funciona bem se o produto vive lá. A ferramenta importa menos do que se ela é reaberta.

Como evito que pedidos de funcionalidades se dupliquem? Agrupe por capacidade subjacente antes de triar por redação. Uma busca entre os pedidos existentes antes de criar um novo pega a maioria das duplicatas; uma passada mensal de agrupamento pega o resto. Mesclar duplicatas sem perder a voz original cobre o que fazer com a redação assim que o agrupamento em si estiver pronto, para que a mesclagem não estreite silenciosamente o pedido para o que quer que a submissão que chegou primeiro tenha pedido.

Todo pedido de funcionalidade deveria receber uma resposta? Todo pedido deveria receber uma confirmação, mesmo curta, mas nem todo precisa de uma decisão na hora. Um status visível, como uma etiqueta de roadmap que quem pediu pode conferir sozinha, substitui a maioria das respostas individuais que um time teria que dar de outra forma.

Qual é a diferença entre rastreamento de pedidos e um roadmap público? Rastreamento é o registro interno de todo pedido, incluindo os que nunca serão lançados. Um roadmap público é o subconjunto ao qual um time se compromete publicamente, com um status que quem pediu pode ver sem perguntar de novo.

Quando um pedido de funcionalidade é na verdade um bug

Mon, 07 Sep 2026 00:00:00 GMT

"Vocês podem adicionar uma configuração para aumentar o limite de exportação?" se lê como um pedido de funcionalidade, e a maioria dos sistemas de triagem etiqueta assim na hora. Às vezes é. Às vezes a exportação falha em um número abaixo do limite documentado por causa de um bug, e a cliente, incapaz de ver o código, inventou a solução mais plausível que consegue descrever: me dê um número maior e talvez funcione. Quais etiquetas valem a pena cobre a etiqueta de tipo que divide um backlog em pedidos de funcionalidade e bugs; este é o caso em que as próprias palavras de uma cliente apontam a etiqueta na direção errada, e o custo de errar é uma deriva lenta para um backlog cheio de pedidos que ninguém realmente quer quando se olha por baixo.

Como é um pedido de funcionalidade que na verdade é um bug?

Ele nomeia um contorno em vez do problema. Um pedido de funcionalidade genuíno geralmente descreve um resultado que o produto não suporta de jeito nenhum: "me deixe agendar isso para depois", "adicionem um modo escuro". Um bug classificado errado descreve um número, limite ou comportamento específico que soa como uma configuração faltando mas na verdade é um sintoma: "aumentem o timeout", "adicionem uma opção de retry", "me deixem exportar mais linhas de uma vez". O sinal é que quem pede propõe uma implementação, uma configuração, um interruptor, uma sobreposição, em vez de descrever um objetivo, porque já testou a funcionalidade como está documentada e ela não fez o que a documentação diz que deveria fazer.

Sinal	Pedido de funcionalidade	Bug disfarçado de pedido de funcionalidade
O que quem pede descreve	Um resultado que o produto não consegue fazer	Um parâmetro que quer mudar
Se o comportamento documentado já cobre isso	Não, realmente faltando	Sim, mas não funciona como documentado
Se mais esforço faz o pedido sumir	Não	Às vezes, se o bug depende de um limite
Para onde deveria ser roteado	Backlog de produto	Fila de bugs

Por que isso importa mais do que parece?

Porque as duas filas têm donas, prazos e critérios de sucesso diferentes, e um bug arquivado como pedido de funcionalidade é priorizado contra pedidos de funcionalidade, competindo por atenção com lacunas reais de produto em vez de ser corrigido no prazo que um bug merece. Como rastrear pedidos de funcionalidade cobre por que misturar bugs e funcionalidades em uma fila só deixa as reclamações mais barulhentas passarem na frente dos pedidos reais; um pedido de funcionalidade que secretamente é um bug faz o dano oposto, fica no backlog de produto acumulando votos para uma "funcionalidade" que sumiria assim que o bug de base fosse corrigido, o que desperdiça o sinal de priorização para quem lê aquele backlog.

Como distinguir quando as próprias palavras da cliente apontam na direção errada?

Pergunte o que ela esperava que acontecesse, não o que quer que vocês adicionem. "A exportação travou em 500 linhas e eu preciso de 2.000, vocês podem aumentar o limite" soa como um pedido de funcionalidade de aumento de limite até a pergunta de acompanhamento, "500 é o limite documentado", revelar que o número documentado era 5.000 e a exportação falha cedo demais. Só essa pergunta, o que ela esperava contra o que aconteceu, faz a maior parte do trabalho de triagem, porque um pedido de funcionalidade genuíno não tem um comportamento documentado do qual fica aquém; não há nada a esperar porque a capacidade ainda não existe.

Agentes de suporte ou engenheiras deveriam decidir isso?

Agentes de suporte fazem a primeira passagem, porque veem o ticket primeiro, mas a etiqueta deveria ser fácil de mudar e barata de errar, não uma decisão única que trava o item na fila errada para sempre. Uma segunda verificação leve, uma engenheira que passa os olhos semanalmente pelas novas etiquetas de "pedido de funcionalidade" atrás de qualquer coisa que cheire a bug disfarçado, pega as que um agente de suporte sem contexto de código não conseguiria reconhecer. Não precisa ser formal; é mais um olhar de cinco minutos do que um processo de revisão.

Fechar o loop muda depois que o bug de verdade é encontrado?

Sim, e melhora a mensagem que vocês podem enviar. Fechar o loop de feedback do cliente cobre avisar quem pediu quando o pedido é lançado; um bug recategorizado ganha uma versão melhor dessa mensagem, porque "encontramos e corrigimos o bug por trás disso" soa como competência, enquanto "construímos a funcionalidade que vocês pediram" só seria verdade por acidente, porque o pedido de funcionalidade real, um limite de exportação de verdade maior, talvez nunca seja construído assim que o bug sumir e o limite original de 5.000 linhas for suficiente.

O que acontece se a classificação errada nunca é percebida?

O backlog se enche de pedidos que parecem demanda real e não são, e as decisões de priorização tomadas contra aquele backlog herdam a distorção. Uma "funcionalidade" com quarenta votos pode na verdade ser quarenta pessoas esbarrando no mesmo bug, e construir o pedido literal, uma configuração para aumentar um limite que nunca foi de fato a restrição, entrega complexidade que não conserta nada, enquanto o bug de base continua gerando novos "pedidos de funcionalidade" de clientes que ainda não encontraram este tópico.

FAQ

Vale a pena adicionar um passo formal para checar cada pedido de funcionalidade contra bugs conhecidos? Não um passo formal, mais um hábito: quem quer que triage um novo pedido de funcionalidade deveria perguntar "o comportamento documentado já afirma fazer isso" antes de aplicar a etiqueta, porque só essa pergunta pega a maioria das classificações erradas sem adicionar sobrecarga de processo.

E se a cliente insistir que é um pedido de funcionalidade mesmo depois do bug ser encontrado? Expliquem o que encontraram e por que a configuração que ela propôs não seria mais necessária assim que o bug for corrigido. A maioria das clientes pede um contorno porque assumiu que o conserto de verdade não estava disponível, não porque queria especificamente aquela configuração.

Um item recategorizado perde os votos ou comentários que acumulou como pedido de funcionalidade? Deveria mantê-los, visíveis, porque esses votos são a evidência que levou a encontrar o bug em primeiro lugar, e esconder esse rastro dificulta pegar a mesma classificação errada da próxima vez, em um ticket diferente.

Isso pode acontecer ao contrário, um relatório de bug que na verdade é um pedido de funcionalidade? Menos vezes, mas sim: "isso está quebrado" às vezes significa "isso não faz o que eu assumi que faria", que é uma capacidade faltando, não um defeito. A mesma pergunta, o que ela esperava contra o que está documentado, classifica também nessa direção.

Tags do git, lançamentos e o seu changelog

Mon, 07 Sep 2026 00:00:00 GMT

Uma tag do git, um lançamento e uma entrada de changelog são três registros diferentes do mesmo evento, e confundi-los faz um changelog se desviar silenciosamente do que realmente foi lançado. Uma tag marca um commit. Um lançamento empacota essa tag com artefatos e uma descrição. Uma entrada de changelog explica, em termos que uma leitora fora do repositório consegue usar, o que mudou. Eles geralmente acontecem próximos no tempo, e é exatamente por isso que é fácil tratá-los como um único passo em vez de três, e exatamente por isso que a lacuna só fica visível meses depois, quando alguém pergunta "o que saiu na v2.4" e a resposta honesta exige uma investigação de verdade.

Qual é a diferença real entre os três?

Registro	Vive em	Escrito para
Tag do git	O repositório, como uma referência	Quem faz checkout exatamente daquele commit
Lançamento	O hospedeiro de código (GitHub, GitLab)	Quem baixa um build
Entrada de changelog	O próprio changelog do produto	Quem usa o produto, não só o repo

Uma tag é a mais mecânica dos três: git tag v2.4.0 e pronto, sem nenhuma exigência de que algo explique o que ela contém. Um lançamento adiciona uma descrição e, geralmente, artefatos para download, e o público continua sendo desenvolvedoras que sabem o que é uma página de lançamento. Uma entrada de changelog é a única dos três escrita para uma leitora que talvez nunca abra o repositório, por isso é a que precisa de mais atenção editorial e a mais provável de ser pulada sob pressão de prazo.

Toda tag do git precisa de uma entrada de changelog?

Não, e tratá-las um a um é um erro comum. Uma tag pode marcar um marco interno, um release candidate, ou um hotfix que nunca chega à maioria das usuárias; nenhuma delas necessariamente precisa de uma entrada pública. O teste é o mesmo que decide se algo pertence a um changelog: se uma usuária ou quem chama notaria ou se importaria. A maioria das tags passa nesse teste. Algumas, como uma tag criada só para disparar um pipeline de CI, nunca.

Toda entrada de changelog precisa da própria tag?

Nem sempre, e é aqui que os times que fazem deploy contínuo divergem dos times que lançam pacotes versionados. Um produto SaaS que faz deploy várias vezes por dia pode agrupar vários deploys sob uma entrada de changelog datada sem uma tag 1:1 por deploy; uma biblioteca publicada em um registro de pacotes geralmente precisa de uma tag por versão publicada. Os módulos Go e o Swift Package Manager resolvem versões a partir das próprias tags; no npm ou no PyPI é o registro que guarda a versão publicada, e a tag é como qualquer pessoa liga essa versão de volta ao código-fonte. Um repositório com vários pacotes versionados de forma independente precisa decidir isso por pacote, não uma vez para o repositório inteiro; changelogs em monorepo cobre como os prefixos de tag e o escopo do changelog deveriam seguir os limites dos pacotes, não das pastas. Semantic versioning e o seu changelog cobre como o número de versão em si deveria mapear para as categorias de changelog; tags são o mecanismo que torna um número de versão verificável contra o código real.

Como uma descrição de lançamento deveria se relacionar com a entrada de changelog?

Podem ser o mesmo texto, mas só se o público dos dois for realmente o mesmo, o que é mais raro do que parece. Uma página de lançamento em um hospedeiro de código é lida quase exclusivamente por desenvolvedoras; se um produto também tem usuárias não técnicas lendo o changelog, duplicar a descrição do lançamento ao pé da letra manda termos internos e uma redação voltada para código a uma leitora que precisava da versão em linguagem simples. O padrão mais limpo: escrever a entrada de changelog como o artefato principal, voltado para a leitora, e deixar a descrição do lançamento linkar para ela ou manter um resumo mais curto e técnico para o público que já está confortável ali.

# Lançamento v2.4.0 (GitHub, para desenvolvedoras)
Atualiza o pipeline de relatórios para o novo motor de agregação. Veja
o changelog para o resumo voltado ao cliente:
https://example.com/changelog#v2.4.0

## 2026-09-07 (Changelog, voltado ao cliente)
### Added
- Relatórios agora carregam em menos de um segundo, mesmo para contas
  com mais de um milhão de linhas.

O mesmo lançamento, dois documentos, cada um com sua própria redação para sua própria leitora.

De onde a entrada de changelog realmente vem?

De dois pontos de partida, e a maioria dos pipelines reais é uma mistura dos dois. Ela pode ser gerada a partir de mensagens de commit no momento da tag, o que é rápido e nunca perde um pull request mesclado; de conventional commits a changelog cobre esse pipeline por completo. Ou pode ser escrita à mão, totalmente separada da tag, sincronizada com o momento em que uma funcionalidade é considerada pronta em vez do momento em que o código é mesclado. Entradas geradas são consistentes mas herdam cada mensagem de commit vaga; entradas escritas à mão são mais claras mas precisam de alguém para realmente escrevê-las. A maioria dos times que automatizam ainda mantém uma passada leve de edição no texto gerado antes que ele vire a entrada pública, a mesma disciplina que Keep a Changelog, na prática recomenda, independentemente de onde o texto bruto veio originalmente.

O que quebra quando os três saem de sincronia?

A confiança no que a leitora conferiu primeiro. Uma tag que existe sem uma entrada de changelog correspondente parece, do lado de quem lê o changelog, que nada aconteceu naquela semana. Uma entrada de changelog sem tag ou lançamento correspondente torna impossível para quem está depurando um problema de produção fazer checkout exatamente do código que estava ao vivo quando uma entrada foi publicada. A solução não é automação perfeita, é uma única fonte de verdade para esse mapeamento: um lugar, mesmo que seja só a própria checklist do processo de lançamento, que diz que uma mudança lançável recebe as três, no mesmo commit ou pull request que a introduz.

FAQ

Entradas de changelog deveriam ser geradas automaticamente a partir de tags do git? Podem ser um ponto de partida, mas uma tag sozinha não carrega nenhuma descrição voltada para a leitora, só um intervalo de commits. A geração automatizada precisa ler as mensagens de commit dentro desse intervalo, não só a existência da tag, para produzir algo utilizável.

E se não colocarmos tag em todo lançamento? Então a entrada de changelog vira o registro principal, e ainda assim deveria carregar uma data e, se o produto tiver uma, um número de versão, para que a entrada continue sendo algo a que uma leitora possa se referir depois mesmo sem uma tag correspondente.

Tags de pré-lançamento (como v2.4.0-rc.1) deveriam ter entradas de changelog? Geralmente não. Um release candidate é para testes internos ou beta, e uma entrada de changelog para ele treina leitoras a esperar entradas para versões que podem nunca ser lançadas exatamente como descritas. Reserve entradas para tags que alcançam disponibilidade geral.

Uma única entrada de changelog pode cobrir várias tags do git? Sim, e frequentemente deveria para times que colocam tag com frequência. Agrupe tags relacionadas sob uma entrada datada descrevendo a mudança líquida, em vez de publicar uma entrada fina por tag que fragmenta uma funcionalidade em várias leituras.

Changelogs de API internas: o que muda para o outro time

Mon, 07 Sep 2026 00:00:00 GMT

Todo outro artigo neste hub assume que quem chama uma API está fora da empresa: a engenheira de uma cliente, uma parceira, alguém que achou a documentação sozinho. Muitas APIs têm um tipo de chamador completamente diferente, um time na sala ao lado ou a dois andares de distância, e isso muda a conta do que um changelog deve a ele, porque uma mensagem no Slack alcança essa pessoa e normalmente nenhum ticket de suporte chega a ser aberto. A maioria dos times conclui daí que APIs internas não precisam de changelog. O que realmente precisam é de um diferente.

O que torna o changelog de uma API interna diferente do de uma pública?

O público é alcançável diretamente, o que remove o principal motivo pelo qual a maioria dos changelogs de API pública existe: transmitir para chamadores que não podem ser contatados individualmente. O time dono de uma API interna geralmente sabe exatamente quais outros times a chamam, às vezes até o serviço específico. Isso faz de uma mensagem direcionada, não um feed público, a escolha padrão natural, e é por isso que APIs internas tão frequentemente acabam sem nenhum changelog: o time dono avisa os dois ou três times que lembra, presumindo que isso cobre todo mundo.

	Changelog de API pública	Changelog de API interna
Quem lê	Qualquer chamador externo, geralmente inalcançável diretamente	Um conjunto pequeno, geralmente conhecido, de times internos
Canal padrão	Uma página e um feed	Uma mensagem para os times chamadores, idealmente também uma página
Maior risco	Um chamador perde a entrada completamente	O time dono esquece um chamador cuja existência nem lembra
O que substitui "não sabemos quem nos chama"	Nada; publicar amplamente	Um registro real de chamadores, mantido atualizado

Por que "simplesmente avisamos os times que nos chamam" falha?

Porque o conjunto de chamadores nunca é tão pequeno ou estático quanto o time dono lembra. Um serviço construído para uma consumidora ganha um segundo chamador seis meses depois, por uma integração que ninguém anunciou, e a lista mental de "quem nos chama" do time dono agora está errada sem que ninguém perceba. A falha é comum e ordinária, o resultado padrão de confiar na memória em vez de em um registro, não um sinal de que alguém foi descuidado. O que é um breaking change cobre como decidir se uma mudança de API sequer conta como quebradora; o caso interno adiciona uma segunda pergunta, mais difícil, em cima dessa: saber a quem avisar.

Uma API interna sequer precisa de uma página de changelog no estilo público?

Geralmente sim, mesmo que o canal principal seja direto. Uma página dá à mensagem direta algo para apontar, então o aviso pode ficar curto ("breaking change em /v2/accounts, detalhes aqui") em vez de tentar carregar toda a explicação em uma mensagem de chat que vai sumir na rolagem. Também se torna o que um time novo, ou um que perdeu a mensagem direta, pode conferir quando a integração dele quebra e ele tenta entender por quê. A página não precisa ser polida nem pública; precisa ser linkável e sobreviver ao tópico do Slack que a anunciou.

Quem realmente mantém a lista de chamadores?

O time dono, e isso precisa ser tratado como um artefato de verdade, não como conhecimento tribal. A versão mais barata é um arquivo no próprio repositório da API, uma lista curta de serviços consumidores com uma responsável por entrada, atualizada toda vez que uma nova integração é construída, a mesma disciplina de qualquer declaração de dependência. A alternativa, perguntar por aí antes de cada breaking change, funciona até aquela vez em que alguém esquece de perguntar à pessoa certa, e uma API interna que quebra silenciosamente para um time é um incidente menor que um público, mas continua sendo um incidente, geralmente descoberto pelo próprio plantão daquele time em vez de pela dona da API.

# consumers.yml
- service: billing-service
  owner: "#team-billing"
  since: 2026-03-01
- service: reporting-pipeline
  owner: "#team-analytics"
  since: 2026-06-14

Um arquivo assim transforma "a quem precisamos avisar" de uma pergunta em uma consulta. Ferramentas construídas exatamente para esse problema, como o catálogo de serviços do Backstage, modelam APIs como entidades de primeira classe com consumidores declarados pela mesma razão: assim que uma organização tem serviços internos suficientes, a memória de ninguém sobre quem chama o quê continua precisa sozinha, e algo precisa guardar esse registro no lugar dela. A documentação de qualquer ferramenta que vocês já rodem internamente geralmente é o lugar certo para checar antes de construir uma própria.

O que pertence a uma entrada de changelog interna que uma pública não precisaria?

Mais especificidade operacional, porque quem lê é outra engenheira que vai agir com base nisso dentro da mesma infraestrutura, não ler isso como um resumo. Em quais ambientes a mudança está no ar e quando, porque serviços internos costumam ser promovidos por estágios que um chamador público nunca vê. Se a mudança exige uma atualização de configuração ou de biblioteca cliente do lado da consumidora, formulada como um comando se existir um. E, porque chamadores internos costumam poder coordenar a correção diretamente com o time dono, um contato nomeado em vez de um canal de suporte: "avise a @maria se isso quebrar alguma coisa" é uma linha perfeitamente razoável em uma entrada interna e uma estranha em um changelog de API pública.

Isso se aplica do mesmo jeito a um changelog dentro de um monorepo?

Isso agudiza o mesmo problema em vez de substituí-lo. Changelogs de monorepo cobre quando um pacote precisa do próprio changelog; uma API interna que é um entre vários pacotes em um monorepo ainda precisa que seus consumidores sejam rastreados explicitamente, porque compartilhar o mesmo repositório com quem a chama não significa que essas pessoas vão notar uma mudança a menos que algo diga a elas para olhar. Proximidade no repositório não é a mesma coisa que proximidade na atenção.

FAQ

Uma API puramente interna precisa de changelog se tiver só um chamador? Quase nada, e uma mensagem direta para esse único time geralmente basta. O changelog se paga assim que existe mais de um chamador, ou assim que a lista de chamadores já surpreendeu o time dono uma vez, porque esse é o sinal de que a memória sozinha não é mais confiável.

Mudanças de API internas deveriam passar pela mesma revisão que as públicas? A redação pode ser mais leve, já que quem lê é uma colega e não uma chamadora externa, mas a decisão de se uma mudança é quebradora merece o mesmo cuidado nos dois casos. Uma chamadora interna ainda tem código em produção que depende do comportamento antigo.

Como descobrir quem chama uma API interna se isso nunca foi rastreado? Logs do servidor ou dados de tráfego de um service mesh são a resposta honesta se nenhum registro de consumidores nunca foi mantido; trate essa descoberta como o momento de começar um, não como uma faxina única.

Uma mensagem no Slack basta, ou uma mudança interna ainda precisa de uma entrada formal de changelog? As duas coisas, para qualquer coisa que não seja puramente aditiva. A mensagem é o que se lê a tempo; a entrada é o que um time investigando um problema semanas depois, que nunca viu a mensagem, ainda consegue encontrar.

Release notes internas: quem mais precisa saber

Mon, 07 Sep 2026 00:00:00 GMT

Todo outro artigo neste hub assume que quem lê uma release note é um cliente. Suporte, vendas e customer success também leem, ou tentam, e a maioria descobre o que foi lançado porque um cliente pergunta primeiro. Essa ordem está invertida, e também é o padrão na maioria das empresas, porque o processo de lançamento termina no momento em que a nota voltada para o cliente sai, e ninguém construiu um segundo passo, menor, para as pessoas que precisam responder perguntas sobre isso uma hora depois.

O que é uma release note interna, e como ela difere de uma voltada para o cliente?

É um documento mais curto, escrito para pessoas que já conhecem o produto a fundo, que diz a elas o que mudou e o que fazer sobre isso no trabalho concreto delas. Um agente de suporte não precisa do enquadramento polido que um anúncio para clientes usa; ele precisa saber como a mudança parece no produto agora, qual será a pergunta mais provável sobre ela, e se tickets abertos são afetados. Uma nota voltada para o cliente vende a mudança. Uma interna equipa alguém para lidar com ela.

Público	O que precisa saber	Onde precisa disso
Suporte	O que mudou na interface, perguntas prováveis, tickets abertos afetados	Onde já procura respostas
Vendas	O que isso desbloqueia para um negócio, o que ainda não faz	Onde se prepara para ligações
Customer success	O que dizer a clientes existentes, e quem pediu	Onde planeja o contato
Liderança	O que foi lançado em relação ao prometido, e quando	Um resumo curto e recorrente, não a cada lançamento

Por que times internos descobrem lançamentos tarde?

Porque o processo de lançamento geralmente é construído em torno de um único artefato, a nota voltada para o cliente ou a entrada de changelog, e presume-se que tudo interno decorra da leitura desse único documento. Não é assim. Agentes de suporte estão ocupados com o ticket na frente deles, não folheando um changelog atrás de contexto, e uma nota escrita para um cliente frequentemente omite justo o detalhe operacional que um agente precisa, como a qual plano a funcionalidade está vinculada ou como é a mensagem de erro quando algo falha. Quando o cliente pergunta, o agente está lendo a mesma nota pública que o cliente acabou de ler, sem nenhuma vantagem.

O que uma release note interna deveria dizer que uma voltada para o cliente não diz?

Os detalhes operacionais que uma nota voltada para o cliente omite de propósito. Quais planos ou contas têm isso. Como é quando algo dá errado, e o que dizer a um cliente que encontrar isso. Se isso fecha algum pedido ou ticket aberto, e quais, para que um agente trabalhando em um ticket relacionado saiba que precisa verificar. Quem no time é responsável se uma pergunta for além do que a nota cobre. Nada disso pertence à versão voltada para o cliente, escrita para ser lida uma única vez por alguém de fora da empresa; tudo isso é exatamente o que precisa quem responde à mesma pergunta quarenta vezes por semana.

Nota interna: exportação em massa de CSV (sai em 08/09/2026)

- Só para os planos Team e Enterprise. Free e Pro sem mudança.
- Falha comum: exportações acima de 50 mil linhas dão timeout;
  problema conhecido, correção rastreada separadamente. Diga ao
  cliente para filtrar por intervalo de datas.
- Fecha 14 pedidos abertos com a etiqueta `bulk-export`. Modelo
  de resposta no documento compartilhado.
- Responsável: time platform, #platform-eng para qualquer coisa
  além desta nota.

Quatro linhas que um agente de suporte pode usar imediatamente, nenhuma delas pertenceria à entrada pública de changelog da mesma funcionalidade.

Quem deveria escrevê-la, e quando?

Quem escreve a nota voltada para o cliente costuma ser a pessoa certa, porque já tem todo o contexto, mas deveria ser uma passada separada e curta em vez de tentar fazer um único documento servir aos dois públicos. Juntar os dois produz ou uma nota voltada para o cliente sobrecarregada de detalhes internos, ou uma nota interna polida demais para ser realmente útil, e na prática é mais rápido escrever dois documentos curtos do que negociar um único documento para servir dois públicos ao mesmo tempo. O momento certo importa mais do que quem escreveu: a nota interna precisa sair antes da voltada para o cliente, mesmo que só por algumas horas, para que o suporte nunca descubra uma mudança no mesmo lugar que um cliente.

Onde ela deveria viver para o suporte realmente encontrá-la no momento de um ticket?

Onde o time já procura coisas quando um ticket chega, não em um changelog separado que ninguém tem motivo para abrir por conta própria. Um time de suporte que usa uma base de conhecimento compartilhada precisa da nota lá, ligada de onde os tickets sobre aquela parte do produto já estão etiquetados. Um time que vive em um canal compartilhado precisa dela publicada lá, pesquisável, no momento em que é relevante, em vez de enterrada em um resumo diário que olham uma vez. O padrão voltado para o cliente de notificação direcionada versus digest se aplica aqui também: uma nota interna sobre uma mudança específica e iminente deveria chegar ao time diretamente, não esperar por um resumo semanal que chega depois que o primeiro ticket já existe.

Ela precisa do mesmo rigor de revisão que a externa?

Menos, e isso é proposital. Uma nota voltada para o cliente representa a empresa publicamente e merece uma passada de edição cuidadosa; uma nota interna existe para ser rápida e concreta, e mantê-la no mesmo padrão de polimento costuma ser exatamente o que faz os times pararem de escrevê-la de vez. Uma nota interna rápida e um pouco crua que sai uma hora antes do lançamento vence uma polida que chega no dia seguinte, quando o primeiro ticket de suporte já chegou confuso.

FAQ

Release notes internas deveriam passar pelo mesmo processo de aprovação que as voltadas para o cliente? Não. Uma passada mais leve e rápida é justamente o objetivo. Exigir a mesma revisão transforma uma nota interna do mesmo dia em uma da semana seguinte, quando o suporte já respondeu a pergunta sem ela.

Quem é responsável por release notes internas se não existe um papel dedicado de comunicação interna? Quem escreve a nota voltada para o cliente, como uma segunda passada curta logo em seguida. Não precisa de um responsável separado, só do hábito de não tratar a nota voltada para o cliente como o único artefato que um lançamento produz.

Release notes internas precisam do próprio changelog ou arquivo? Um lugar pesquisável vence um arquivo cronológico que ninguém rola. Se o suporte já tem uma base de conhecimento, a nota pertence lá, etiquetada com a funcionalidade, em vez de em um changelog interno separado que só ajuda quem já sabe a data do lançamento.

Qual é o risco de pular release notes internas em mudanças pequenas? Mudanças pequenas são justamente aquelas em que o suporte recebe perguntas sem aviso, porque uma mudança pequena raramente recebe um anúncio para a empresa inteira. O tamanho da release note deveria escalar com o tamanho da mudança; nunca deveria cair para zero só porque a mudança foi pequena.

Release notes para apps mobile: o que o limite corta

Mon, 07 Sep 2026 00:00:00 GMT

Tudo neste hub sobre escrever release notes assume uma página que você controla totalmente: qualquer tamanho, links que funcionam, formatação que renderiza. As release notes de um app mobile vivem dentro da caixa de outra empresa. A Apple dá cerca de 4.000 caracteres mas só mostra as primeiras linhas antes de "mais" ser tocado; o Google dá um espaço parecido com o mesmo problema efetivo de prévia, e nenhuma das duas plataformas renderiza um link clicável dentro do texto. As regras de como escrever release notes que as pessoas realmente leem ainda valem: diga o que mudou e o que a leitora precisa fazer, mas o espaço para isso é uma fração do que uma página de changelog permite, e os cortes precisam ser feitos de propósito, não por acidente.

O que realmente cabe na prévia visível?

As primeiras uma ou duas linhas, algo entre 80 e 170 caracteres dependendo do aparelho e do tamanho da fonte, antes de a leitora precisar tocar para expandir. Esse é todo o orçamento para a parte da release note que decide se alguém vai ler o resto, e isso significa que a frase mais importante precisa vir primeiro, não o número da versão, não uma saudação, não um título de categoria. Uma release note que começa com "Novidades desta versão:" já gastou um terço do seu espaço visível em quatro palavras que não dizem nada para a leitora.

Plataforma	Limite total aproximado	Prévia efetiva antes de "mais"
App Store (iOS)	~4.000 caracteres	2-3 linhas, cerca de 80-170 caracteres
Google Play	~500 caracteres por idioma, alguns campos mais curtos	2-3 linhas, parecido com iOS
As duas	Nenhum link clicável no campo de release notes	N/A

A regra "o que você pode fazer agora, o que se deve a você" ainda funciona nesse tamanho?

Funciona, e fica mais rígida, não diferente. Uma frase por entrada, verbo primeiro, sem introdução: "Exporte seus dados como CSV em Configurações." vence "Adicionamos a capacidade de os usuários agora poderem exportar seus dados em formato CSV" usando um terço das palavras para dizer a mesma coisa. No tamanho de uma página de changelog, uma frase um pouco mais prolixa custa meio segundo à leitora. No tamanho de uma release note mobile, essa mesma prolixidade pode empurrar a frase inteira para fora da prévia visível, então a leitora nunca vê o verbo que diria a ela o que mudou.

Ruim, desperdiça a prévia com enquadramento:
"Estamos animados em trazer uma nova atualização
cheia de melhorias! Continue lendo para os detalhes."

Bom, todo o valor na primeira linha:
"Exporte seus dados como CSV. O modo escuro agora
respeita a configuração do sistema. Corrigido um
travamento ao abrir links compartilhados."

O que precisa ser cortado do que uma entrada de changelog web normalmente manteria?

Links, primeiro, porque nenhuma das duas lojas os renderiza como clicáveis, então uma URL no texto é peso morto que a leitora teria que digitar de novo. Se a entrada precisa de um destino, diga em vez disso o que tocar no app: "Veja os novos filtros em Configurações > Busca" funciona; "Leia mais em example.com/blog/filtros" não funciona nessa superfície. Segundo, qualquer coisa condicional ou específica de um público: um changelog web pode dizer "se você usa a API, isso te afeta", mas uma listagem de loja alcança cada usuária instalada ao mesmo tempo, então uma linha condicional soa como ruído para os 95% a quem não se aplica. Coloque o detalhe condicional em uma mensagem dentro do app em vez disso, disparada para as contas que ele realmente diz respeito.

Cada lançamento deveria ter suas próprias notas, ou tudo bem reutilizar "correções de bugs e melhorias de performance"?

Reutilize para lançamentos que genuinamente são isso, mas audite com que frequência isso é realmente verdade. Como escrever release notes já cobre por que essa frase entrega uma nota escrita de dentro em vez de para a leitora; no mobile isso faz um dano duplo, porque as release notes da loja são um dos poucos lugares onde algumas usuárias veem qualquer coisa entre atualizações, e uma longa sequência de "correções de bugs e melhorias de performance" soa como se o app não estivesse mudando, o que causa uma impressão pior do que nenhuma nota naquele período.

As release notes influenciam se as pessoas atualizam o app?

Indiretamente, através de visibilidade em vez de persuasão. A maioria das usuárias atualiza automaticamente e nunca lê as notas antes de atualizar; as notas importam mais para a minoria que confere atualizações manualmente, e para quem faz resenhas ou imprensa que percorre o histórico de uma listagem de loja. Escrever para esse público menor ainda vale a pena, porque uma listagem com um histórico real de entradas específicas e datadas se lê como um app mantido ativamente, e uma listagem com um ano de "correções de bugs e melhorias de performance" não, não importa quanto tenha sido realmente lançado naquele período.

E uma atualização forçada, onde a nota precisa explicar por que a usuária não tem escolha?

Indique o motivo e o prazo na primeira linha, antes de qualquer outra coisa, porque uma atualização forçada é o único caso em que a leitora já está incomodada antes mesmo de começar a ler. "Esta atualização é necessária para continuar sincronizando seus dados. Atualize até [data] para evitar interrupção." diz o que fazer e por quê em uma frase; enterrar esse motivo sob três linhas de notas de funcionalidades sem relação soa como se o app estivesse escondendo a parte inconveniente.

FAQ

As release notes mobile deveriam corresponder ao changelog web do mesmo lançamento? Cobrir as mesmas mudanças subjacentes, mas não palavra por palavra. O changelog web pode se dar ao luxo da explicação completa; a nota mobile precisa dos mesmos fatos comprimidos em uma frase com o verbo primeiro, o que geralmente significa que é uma reescrita, não uma cópia.

Vale a pena localizar as release notes mobile para cada idioma suportado? Vale, mais até do que para um changelog web, porque a listagem da loja é muitas vezes a única superfície localizada que algumas usuárias veem entre sessões, e as duas plataformas suportam release notes por idioma sem trabalho de engenharia adicional além da tradução em si.

Quanto tempo uma release note mobile deveria ter se não houver um limite forçando a brevidade? Curta de qualquer jeito. O teto de 4.000 caracteres no iOS raramente é a restrição real; a restrição é a prévia de 2-3 linhas, e escrever além do que essa prévia mostra só significa que menos pessoas leem a parte que importava.

As release notes precisam do número da versão no texto visível? Não. A loja já mostra o número da versão ao lado das notas. Repeti-lo dentro do texto gasta caracteres visíveis em informação que a leitora já tem na frente dela.

Changelogs em monorepo: um só, ou um por pacote?

Mon, 07 Sep 2026 00:00:00 GMT

Um monorepo abriga várias coisas lançadas separadamente dentro de um único repositório, e um changelog precisa primeiro responder uma pergunta: o leitor se importa com o repositório, ou se importa com um pacote específico dentro dele? A maioria dos times nunca decide isso de propósito. Começam com um changelog porque existe um repositório, vão adicionando pacotes com o tempo, e acabam com um log em que alguém usando a CLI precisa rolar por quarenta entradas do backend sem relação nenhuma até achar a que lançou a correção dele. O que decide a forma certa não é a estrutura do repositório, e sim quem lê o log e o que essa pessoa já sabe que está procurando.

O que faz o changelog de um monorepo ser diferente do de um repositório único?

Um changelog de repositório único tem um público implícito: todo mundo que usa a única coisa que esse repositório constrói. O público de um monorepo se divide por pacote, e pacotes no mesmo repositório muitas vezes são lançados em cronogramas diferentes, para consumidores diferentes, em níveis de estabilidade diferentes. Uma biblioteca publicada em um registro e uma ferramenta administrativa interna podem viver no mesmo monorepo e não ter quase nada em comum para quem lê o changelog.

Formato do repositório	Leitor típico	Changelog que combina
Um único app lançado	Todo mundo que usa o produto	Um log, para o repositório inteiro
Workspace de bibliotecas (vários pacotes publicados)	Quem depende de um pacote específico	Um log por pacote
App mais ferramentas internas	Dois públicos diferentes sem sobreposição	Dividido por público, não por pasta
App mais o próprio SDK	Usuários do produto, e integradores do SDK	Dois logs: um do produto, um do SDK

Todo pacote precisa do próprio changelog?

Só os que têm um público independente. Um pacote publicado em um registro precisa do próprio log, porque quem instala não tem motivo nenhum para ler qualquer outra coisa no repositório, e as ferramentas de release para monorepo como Lerna e Changesets escrevem um CHANGELOG.md por pacote, ao lado do package.json dele. Um utilitário interno com um único consumidor, o app que já vive no mesmo repositório, não precisa de um log separado; incluir as mudanças dele nas entradas desse app é mais útil do que um segundo arquivo que ninguém fora do time abre.

O teste é o mesmo que decide se qualquer entrada pertence a um changelog: o leitor notaria ou se importaria, e consegue agir sabendo disso. Aplique isso por pacote, não por pasta, e um repositório com doze pacotes pode acabar com dois changelogs de verdade e dez pacotes que simplesmente não precisam de um.

Como saber qual pacote causou qual entrada de changelog?

Marque cada entrada com o pacote dela no momento em que é escrita, não depois inspecionando quais arquivos um commit tocou. Um commit que corrige uma biblioteca interna compartilhada pode produzir uma entrada de changelog em cada pacote que depende dela, e os caminhos dos arquivos sozinhos não conseguem dizer qual dessas entradas a jusante o leitor realmente precisa ver; só uma pessoa decidindo "isso é visível para quem usa o pacote A e não para quem usa o pacote B" consegue fazer isso. Conventional commits ajudam aqui mecanicamente, nomeando o pacote em cada commit, mas o escopo ainda assim só produz um rascunho. A mesma regra de duas camadas daquele artigo se aplica por pacote: um rascunho com o escopo certo ainda precisa de uma passada humana antes de ser formulado para o leitor real daquele pacote.

O que um changelog compartilhado precisa que um de repositório único não precisa?

Uma etiqueta de pacote em cada entrada, logo no início, antes da descrição, para que um leitor percorrendo o log consiga, em uma única passada, pular tudo que não é dele. Sem essa etiqueta, um log compartilhado se lê como um feed aleatório, e um leitor interessado em um pacote não tem como filtrá-lo além de memorizar quais linhas contam, o que ninguém faz depois da primeira semana.

## 2026-09-07

### [cli] Adicionado
- `acme push --dry-run` mostra o que seria enviado sem
  enviar de fato.

### [core] Corrigido
- O backoff de novas tentativas não é mais reiniciado em uma
  requisição bem-sucedida que retorna um corpo vazio.

Duas entradas, dois públicos, um olhar para distingui-las. Um fluxo de trabalho no estilo Changesets integra essa marcação diretamente no processo de lançamento: quem contribui escreve uma nota curta, com o escopo do pacote, ao lado da própria mudança, e a ferramenta monta os changelogs por pacote e os saltos de versão a partir dessas notas no momento do lançamento, em vez de tentar reconstruir os limites dos pacotes depois, a partir de um histórico de commits já unificado.

Como o versionamento se relaciona com um changelog de monorepo?

Pacotes versionados de forma independente precisam do próprio changelog porque têm o próprio número de versão, e um changelog compartilhado não consegue expressar "o pacote A foi de 2.1 para 2.2 enquanto o pacote B ficou em 1.4" sem virar dois logs dentro de um único arquivo. Semantic versioning e o seu changelog cobre como o número de versão em si deveria mapear para as categorias de changelog; em um monorepo, esse mapeamento precisa ser aplicado por pacote, porque uma mudança que quebra em um pacote não é uma mudança que quebra para um pacote irmão que não depende dele.

Um repositório que lança um produto como uma única unidade implantável, mesmo que construído a partir de muitos pacotes internos, não tem esse problema: os pacotes compartilham uma versão porque sempre são lançados juntos, e um único changelog é o correto.

Como as tags do git se encaixam em um monorepo?

A mesma regra de tags do git, lançamentos e o seu changelog se aplica, por pacote: um pacote com a própria versão precisa do próprio prefixo de tag, tipicamente nome-do-pacote@1.4.0 em vez de um v1.4.0 nu que não consegue dizer a qual pacote pertence. Um monorepo marcado só com números de versão nus não consegue responder depois "o que tinha em core quando o cli lançou a 2.2", porque nada no disco registra a qual pacote essa tag realmente pertencia.

FAQ

Preciso de um changelog separado para cada pacote em um monorepo? Só para pacotes com público independente, geralmente qualquer coisa publicada em um registro. Um pacote com um único consumidor interno que já vive no mesmo repositório pode entrar no log desse consumidor em vez de manter um próprio.

O que marca uma entrada de changelog com o pacote certo? A pessoa que escreve a entrada, no momento em que a escreve, não uma varredura automática dos caminhos de arquivo alterados. Uma mudança em uma biblioteca compartilhada pode produzir uma entrada diferente em cada pacote que depende dela, e só um humano consegue decidir o que cada uma dessas entradas a jusante deveria realmente dizer.

Um monorepo deveria usar um único número de versão para tudo? Só se cada pacote sempre for lançado junto com os outros. Se os pacotes forem publicados de forma independente algum dia, eles precisam de versões independentes, e versões independentes precisam de changelogs independentes para fazer sentido.

Uma ferramenta de changelog para monorepo substitui a etapa de edição humana? Não. Ferramentas como o Changesets automatizam a coleta e a montagem das notas por pacote no momento do lançamento; a nota em si, escrita na linguagem do leitor em vez da de quem contribuiu, continua sendo trabalho de uma pessoa, assim como em qualquer outro pipeline de changelog.

Como anunciar uma funcionalidade nova (sem silêncio)

Mon, 07 Sep 2026 00:00:00 GMT

A maioria dos anúncios de funcionalidades morre em um canal que ninguém lê duas vezes: um tweet que passa rolando, um e-mail do dia do lançamento enterrado sob os outros doze que uma assinante recebeu naquela semana, uma mensagem no Slack em um canal que metade do time silenciou meses atrás. A funcionalidade foi lançada. Quase ninguém que a usaria ficou sabendo. Consertar isso tem menos a ver com escrever um anúncio melhor e mais com escolher o canal certo para a leitora certa, e alcançar diretamente quem pediu explicitamente por aquilo, em vez de contar com o fato de que vão notar uma mensagem geral.

Onde uma funcionalidade nova deveria realmente ser anunciada?

Em mais de um lugar, porque "todo mundo lê o mesmo canal" nunca é verdade. Uma entrada de changelog ou feed serve a leitora que confere no próprio ritmo e quer o registro permanente e datado. Um aviso no app serve a leitora que já usa o produto e usaria a funcionalidade hoje se soubesse que ela existe. E-mail serve a leitora que não está atualmente no produto mas voltaria pela atualização certa. Redes sociais servem alcance além das usuárias existentes, quase sem segmentação.

Canal	Melhor para	Fraqueza
Changelog / feed	O registro permanente; leitoras que conferem no próprio ritmo	Passivo; não faz nada por quem nunca confere
Aviso no app	Usuárias já presentes que agiriam hoje	Não alcança ninguém que não esteja logada agora
E-mail	Usuárias inativas que voltariam por isso	Fácil de enterrar sob outros e-mails; precisa de um assunto de verdade
Redes sociais	Alcance além das usuárias atuais	Quase sem segmentação; vida útil curta

Nenhum dos quatro é suficiente sozinho. O changelog é o único documento que deveria carregar todo lançamento independentemente do tamanho, porque é o registro para o qual tudo o mais aponta de volta; os outros três são amplificação adicionada por cima, escolhida de acordo com o quão grande a funcionalidade realmente é.

O que o anúncio deveria dizer primeiro?

O resultado, não o mecanismo. "Adicionamos uma camada de cache ao endpoint de relatórios" descreve o que o time construiu. "Relatórios agora carregam em menos de um segundo" descreve o que mudou para a leitora, e essa é a frase que consegue o clique, porque responde "o que eu ganho com isso" na primeira frase em vez da terceira. O mecanismo pertence à entrada do changelog ou à página de detalhes, não ao título.

Concreto antes de adjetivos. "Uma experiência de relatórios mais rápida e poderosa" não diz nada à leitora sobre o que fazer; "relatórios agora carregam em menos de um segundo e podem ser filtrados por status" diz exatamente o que mudou e o que experimentar. A segunda versão também parece mais confiável, porque uma alegação vaga soa exatamente como soa o texto de marketing quando não há nada concreto a dizer.

Como isso difere de um e-mail de atualização de produto?

Se sobrepõem mas não são idênticos. E-mail de atualização de produto cobre o canal de e-mail especificamente, incluindo cadência, assuntos, e quando um digest vence um envio único. Um anúncio de funcionalidade nova é o evento subjacente; o e-mail é um dos quatro canais acima que poderia carregá-lo, escolhido quando a funcionalidade é grande o suficiente para justificar um envio dedicado em vez de andar carona no próximo digest. Uma funcionalidade pequena merece uma entrada de changelog e talvez um aviso no app. Uma significativa merece os quatro canais, coordenados no tempo.

Como alcançar as pessoas específicas que pediram por isso?

Esse é o anúncio com o melhor retorno sobre esforço, e quase todo time o pula. Se dez clientes pediram uma funcionalidade pelo nome, essas dez pessoas merecem uma nota direta e pessoal no momento do lançamento, independentemente de qualquer anúncio mais amplo que saia. Fechando o ciclo de feedback com o cliente cobre a mecânica por completo; o resumo aqui é que isso só funciona se o pedido original continuar ligado a quem o fez, o que é mais um problema de rastreamento do que um problema de anúncio. No changeloop, quando um feedback pelo widget virou uma issue do GitHub e o pull request mergeado a fecha (fixes #142), aprovar a entrada do changelog posta nessa issue o comentário "Shipped — ", uma única vez, com link para a entrada ao vivo, e quem mandou o feedback vê a entrada lançada no widget. Ninguém precisa se lembrar de contar. Issues abertas manualmente, e repositórios GitLab ou Bitbucket, não recebem o comentário.</p> <h2>Como se escreve a entrada em si?</h2> <p>A mesma disciplina de qualquer outra entrada de notas de versão: comece com o que a leitora já pode fazer, continue com a configuração necessária, pule a justificativa interna. <a href="https://changeloop.dev/blog/pt-br/how-to-write-release-notes/">Como escrever notas de versão</a> cobre o método completo; um anúncio de funcionalidade nova é o caso de maior risco, porque é a entrada com mais chance de ser capturada em print, encaminhada, e lida por alguém que nunca viu o changelog do produto.</p> <h2>Quando não anunciar amplamente?</h2> <p>Quando a funcionalidade ainda está sendo lançada para um subconjunto de contas, é realmente uma beta, ou tem preço ou bloqueio tais que nove em dez leitoras de um anúncio amplo ainda não conseguiriam usá-la. Um anúncio amplo para uma funcionalidade que nove em dez leitoras não podem usar se lê como uma isca, e queima a confiança no próximo anúncio mais do que constrói entusiasmo neste. A solução não é o silêncio, é o alcance: informe diretamente as contas elegíveis e segure os canais amplos até a disponibilidade alcançar o anúncio.</p> <h2>FAQ</h2> <p><strong>Toda funcionalidade nova merece seu próprio anúncio?</strong> Todas merecem uma entrada de changelog. Só as significativas o suficiente para mudar como alguém usa o produto, ou as pedidas explicitamente pelo nome, merecem os canais mais amplos como e-mail ou redes sociais.</p> <p><strong>Qual é o melhor canal para uma funcionalidade pequena?</strong> Só o changelog, mais um aviso no app se a funcionalidade for descobrível em um fluxo em que a usuária já está. E-mail e redes sociais valem a pena para funcionalidades que justificam pedir atenção.</p> <p><strong>Como anunciar uma funcionalidade às pessoas que especificamente pediram por ela?</strong> Mantenha o pedido ligado a quem o fez desde o momento em que é registrado, depois notifique individualmente no lançamento, separado de qualquer anúncio mais amplo. Uma etiqueta de status compartilhada que quem pediu pode conferir sozinha também reduz quantas mensagens individuais são necessárias em primeiro lugar.</p> <p><strong>Um anúncio de funcionalidade precisa de um print?</strong> Para qualquer coisa visual, sim; uma funcionalidade descrita mas não vista é pulada com muito mais frequência do que uma para a qual as leitoras conseguem ver uma prévia. Para uma API ou capacidade de backend, um exemplo de código curto faz o mesmo trabalho que um print faria para uma mudança de UI.</p> </article> <article> <h1>Como priorizar pedidos de funcionalidades</h1> <p>Mon, 07 Sep 2026 00:00:00 GMT</p> <p>Rastrear pedidos de funcionalidades resolve onde eles vivem. Não resolve qual sai primeiro, e essa segunda pergunta é onde os times realmente travam. Um backlog de trezentos pedidos, já agrupados e etiquetados, ainda precisa de uma regra de decisão, porque "construa o que foi mais pedido" só funciona até dois pedidos ficarem próximos e um terceiro ter uma defensora barulhenta, o que acontece na maioria das semanas. Os frameworks abaixo não são respostas concorrentes para a mesma pergunta. Cada um combina com um tipo diferente de pedido, e usar só um para todos costuma ser o erro de verdade.</p> <h2>O que diferencia priorizar pedidos de funcionalidades de priorizar um roadmap?</h2> <p>Uma decisão de roadmap parte da estratégia e pergunta o que construir. Uma decisão sobre um pedido de funcionalidade parte de uma demanda que já existe e pergunta se vale agir sobre ela, e as duas puxam para lados diferentes com frequência suficiente para que um pedido tenha demanda alta e ainda assim seja errado construí-lo, ou tenha demanda baixa e ainda assim valha a pena porque desbloqueia uma conta estratégica. Tratar cada pedido como um voto de roadmap pula essa checagem.</p> <table> <thead> <tr> <th>Framework</th> <th>O que pesa</th> <th>Onde falha</th> </tr> </thead> <tbody><tr> <td>Contagem bruta de pedidos</td> <td>Quantas pessoas pediram</td> <td>Recompensa nomes fáceis de lembrar em vez de demanda real</td> </tr> <tr> <td>RICE</td> <td>Alcance, impacto, confiança, esforço</td> <td>Precisa de estimativas que ninguém tem para um pedido novo</td> </tr> <tr> <td>Ponderado por receita</td> <td>Quem pediu, pelo valor da conta</td> <td>Ignora pedidos de contas que ainda não valem muito</td> </tr> <tr> <td>Votos públicos</td> <td>Sinal visível, baixo esforço</td> <td>Só alcança usuários que já sabem onde olhar</td> </tr> </tbody></table> <h2>O que é RICE, e ele funciona para pedidos de funcionalidades?</h2> <p>O <a href="https://www.intercom.com/blog/rice-simple-prioritization-for-product-managers/">RICE</a> avalia uma ideia por alcance, impacto, confiança e esforço, depois divide os três primeiros pelo quarto para chegar a um número comparável. Foi criado para ideias de roadmap em que um time já acredita, onde a parte difícil é comparar apostas diferentes entre si. Pedidos de funcionalidades já vêm com um número de alcance, a contagem de gente que pediu, o que é mais concreto do que o alcance que uma ideia de roadmap recém-nascida costuma ter. Onde o RICE tensiona com um pedido é confiança e impacto: um time pode ter certeza de que um pedido é real e ainda assim não ter base para saber o quanto isso vai mover uma métrica, porque "impacto" para um pedido que já tem nome e um rastro de usuários reais é um tipo diferente de estimativa do que o impacto de uma ideia que ninguém fora da sala ainda viu.</p> <p>Use o RICE para pedidos que estão sendo levados a sério e ainda não foram decididos. Não aplique em todo pedido que chega; o esforço de pontuar só compensa nos que estão próximos o suficiente para precisar de um critério de desempate.</p> <h2>Deveria ponderar por receita, ou por quem pediu?</h2> <p>Por quem pediu, mas não só por receita. Uma conta perto da renovação, uma conta que já escalou antes, e uma conta cujo pedido desbloqueia um negócio em andamento carregam uma urgência que um número plano de receita, sozinho, não capta, e um pedido de um cadastro de teste ainda pode importar se está bloqueando uma decisão que logo vira receita. A ponderação por receita é a mais fácil de calcular entre todas essas, e é justamente por isso a mais fácil de confiar demais: ela remove corretamente o ruído de contas sem interesse real, e com a mesma facilidade pode rebaixar um pedido que traria uma conta muito maior, ainda no funil.</p> <h2>Qual papel os votos realmente cumprem?</h2> <p>Um sinal barato e contínuo para pedidos que já existem, e uma forma ruim de descobrir quais pedidos deveriam existir em primeiro lugar. Uma contagem de votos só alcança usuários que já encontraram o pedido e acharam que valia um clique, o que significa que o total de votos de um roadmap público reflete visibilidade tanto quanto demanda: um pedido antigo perto do topo da lista continua acumulando votos em parte porque é fácil de achar, e um pedido mais novo, igualmente real, começa do zero. O artigo sobre <a href="https://changeloop.dev/blog/pt-br/public-roadmap/">roadmap público</a> defende deixar os votos totalmente fora do roadmap. Trate votos como um sinal que precisa ser agrupado e ponderado por recência, não como um ranking a ser construído em ordem. <a href="https://changeloop.dev/blog/pt-br/feedback-signal-quality/">Tickets de suporte vs. pedidos</a> cobre o outro ponto cego nas contagens de votos: uma lacuna real pode gerar quase nenhum voto se as usuárias que a encontram nunca acharem o quadro, enquanto ainda assim aparece barulhenta no suporte.</p> <h2>Quando o cliente mais barulhento vence, e isso é um problema?</h2> <p>Às vezes, e só é um problema quando ninguém percebe. Um cliente que escala com frequência, escreve tickets detalhados ou tem uma linha direta com alguém do time vai ver os pedidos dele examinados mais rápido do que um cliente mais quieto com um pedido igualmente válido, e um processo de priorização que nunca verifica isso vai favorecer sistematicamente quem mais insiste, não quem tem o caso mais forte. Clientes barulhentos não são o problema a ser corrigido; os pedidos deles costumam ser genuinamente importantes. A correção é um hábito: passar pelo backlog periodicamente por origem e checar se o mesmo punhado de contas explica a maior parte do que foi lançado recentemente, e perguntar se isso bate com onde a demanda real de fato está.</p> <h2>Como uma decisão de priorização vira uma resposta?</h2> <p>Toda decisão aqui produz ganhadores e perdedores, e ambos merecem uma resposta que nomeie o raciocínio real, não só uma mudança de status sem explicação. <a href="https://changeloop.dev/blog/pt-br/declining-feature-requests/">Como recusar um pedido de funcionalidade</a> cobre o que dizer a um pedido que perdeu, de um jeito que mantém a relação intacta em vez de soar como uma recusa genérica. O trabalho de agrupamento e etiquetagem que torna tudo isso possível desde o início está coberto em <a href="https://changeloop.dev/blog/pt-br/feature-request-tracking/">rastreamento de pedidos de funcionalidades</a>; a priorização só funciona sobre pedidos já registrados e agrupados o suficiente para serem comparados.</p> <h2>FAQ</h2> <p><strong>Qual é o melhor framework para priorizar pedidos de funcionalidades?</strong> Nenhum sozinho. Use contagens brutas para achar o sinal mais barulhento, RICE para comparar uma lista curta de candidatos sérios, e uma checagem de receita ou de conta para pegar casos em que uma demanda silenciosa de uma conta estratégica pesa mais do que um grupo mais barulhento, porém menos importante.</p> <p><strong>Pedidos de funcionalidades deveriam ser priorizados do mesmo jeito que ideias de roadmap?</strong> Não. Ideias de roadmap partem da estratégia; pedidos de funcionalidades partem de uma demanda que já existe. Pontuar os dois juntos faz uma aposta estratégica bem argumentada, mas com pouca demanda existente, perder consistentemente para um pedido que simplesmente teve mais gente pedindo.</p> <p><strong>Os votos em um roadmap público refletem a demanda com precisão?</strong> Só entre as pessoas que já encontraram o pedido. Pedidos mais antigos e mais visíveis acumulam votos mais rápido, independentemente de quanta demanda real existe por trás de um mais novo, então trate os totais de votos como um sinal, agrupado e ponderado por recência, não como um ranking a ser construído em ordem.</p> <p><strong>Com que frequência as prioridades de pedidos de funcionalidades deveriam ser reavaliadas?</strong> Em um ciclo fixo, não só quando alguém escala. Uma passada mensal ou trimestral que reagrupa pedidos e reconfere a ponderação pega desvios, como um punhado de contas dominando o que é lançado, que um processo puramente reativo nunca revela sozinho.</p> </article> <article> <h1>Release notes enterprise: o que muda para uma conta</h1> <p>Mon, 07 Sep 2026 00:00:00 GMT</p> <p>Um produto SaaS público envia as mesmas release notes para todo mundo, porque todo mundo está na mesma versão. Uma cliente enterprise em uma versão fixada, uma instância dedicada, ou um subconjunto do produto com feature flags quebra essa suposição: as release notes que descrevem o que mudou para ela não são as mesmas do blog público de vocês, e enviar as públicas mesmo assim ou confunde a cliente com mudanças que ela ainda não tem, ou, pior, conta a ela sobre uma funcionalidade que a equipe de conta de outra cliente enterprise pediu explicitamente para vocês segurarem da instância dela por mais um mês. <a href="https://changeloop.dev/blog/pt-br/release-notes-best-practices/">Melhores práticas para release notes</a> cobre o ofício geral; isto é sobre escrever release notes enterprise para o problema de calibração que só aparece quando vocês têm clientes que não estão todas no mesmo build.</p> <h2>Por que uma cliente enterprise não pode simplesmente ler o changelog público?</h2> <p>Porque ele descreve uma versão que ela talvez ainda não esteja rodando, funcionalidades às quais ela talvez não tenha acesso, e um cronograma que não bate com o dela. Uma cliente fixada em um ciclo de release trimestral que lê sobre uma funcionalidade que saiu para a camada pública semana passada não tem como saber, só pelo changelog público, se essa funcionalidade vai chegar a ela na semana que vem ou no trimestre que vem. O changelog público responde "o que mudou no produto"; a pergunta real de uma cliente enterprise é "o que mudou na versão que estou rodando, e quando eu recebo o resto", algo que o changelog público nunca foi escrito para responder.</p> <h2>Do que uma release note privada precisa que uma pública não precisa?</h2> <p>Um identificador de versão ou ambiente contra o qual a cliente possa realmente conferir, e uma declaração explícita do que ainda não chegou a ela. "Esta release inclui as melhorias de exportação em massa da nossa release pública 4.3, mas não o novo modelo de permissões, que chega na próxima atualização programada de vocês" diz a uma administradora enterprise exatamente onde a instância dela está em relação ao produto como um todo. Uma release note pública nunca precisa desse enquadramento porque só existe uma instância à qual ser relativa; uma privada é sem sentido sem ele.</p> <table> <thead> <tr> <th>Release notes públicas</th> <th>Release notes privadas (enterprise)</th> </tr> </thead> <tbody><tr> <td>Uma versão, uma audiência</td> <td>Múltiplas versões, audiências segmentadas</td> </tr> <tr> <td>Assume que a leitora tem cada funcionalidade descrita</td> <td>Precisa declarar o que a leitora tem e não tem</td> </tr> <tr> <td>Sincronizadas com a release pública</td> <td>Sincronizadas com a própria janela de atualização da cliente</td> </tr> <tr> <td>Podem ser tornadas totalmente públicas de imediato</td> <td>Podem precisar reter itens que outras clientes ainda não têm</td> </tr> </tbody></table> <h2>Alguma vez é aceitável simplesmente atrasar o envio das release notes públicas para clientes enterprise em vez de escrever outras separadas?</h2> <p>Só se a versão dela realmente coincidir com a pública naquele momento, o que é mais raro do que parece assim que vocês têm mais que algumas contas enterprise em ritmos diferentes. Atrasar as notas públicas funciona como solução temporária para uma cliente que está uma versão atrás e prestes a alcançar; isso desmorona no momento em que duas clientes enterprise estão em versões diferentes entre si, porque então não existe mais uma única "as notas" para atrasar, só uma matriz do que cada uma tem. Nesse ponto, calibrar as notas por conta, mesmo que seja só uma visão filtrada das mesmas entradas subjacentes, deixa de ser opcional.</p> <pre><code>Notas públicas, enviadas a uma conta enterprise que ainda não tem a funcionalidade: "New: Bulk export now supports custom column ordering." (Confuso: a admin tenta e não está lá.) Notas enterprise calibradas para a mesma conta: "Available in your next update (scheduled for 2026-10-15): bulk export with custom column ordering. Not yet available on your current version (3.8)." </code></pre> <h2>Quem dentro da organização da cliente realmente lê isso, e isso muda a forma de escrever?</h2> <p>Geralmente uma administradora de TI ou um contato de customer success em vez de uma usuária final, e isso muda o que conta como útil. Uma usuária final quer saber o que parece diferente na tela dela; uma administradora enterprise quer saber o que mudou em permissões, tratamento de dados, configuração de SSO, ou qualquer coisa que afete como ela gerencia a implantação para as próprias usuárias, porque ela vai ser quem responde às perguntas internas. Uma release note privada que se lê como um changelog de consumidor, tudo botões novos e brilhantes e nenhum detalhe operacional, força a administradora a cavar atrás da informação que ela realmente precisava.</p> <h2>Como isso interage com um roadmap público ou changelog público que já lista a mesma funcionalidade?</h2> <p>Com cuidado, porque uma cliente que lê os dois vai notar qualquer inconsistência. Se o changelog público de vocês já anunciou uma funcionalidade que uma conta enterprise específica ainda não tem, a release note privada dela precisa reconhecer essa lacuna em vez de fingir que a entrada pública não existe; uma administradora que viu o anúncio público e recebe notas privadas que o ignoram vai assumir ou que vocês esqueceram dela, ou que algo está quebrado. <a href="https://changeloop.dev/blog/pt-br/public-roadmap/">Roadmap público</a> cobre como manter um roadmap honesto sobre o que foi lançado versus planejado; a versão enterprise dessa honestidade em release notes é nomear diretamente a lacuna entre o que é público e o que é dela.</p> <h2>Uma empresa pequena com só uma ou duas clientes enterprise precisa de tanta estrutura?</h2> <p>Não do sistema totalmente segmentado, mas a disciplina central, declarar claramente em que versão a cliente está e o que ela tem e não tem, importa em qualquer escala assim que vocês têm mesmo que seja uma cliente que não está no build mais recente de vocês. O modo de falha que isso previne, uma administradora confusa se um anúncio público se aplica a ela, custa um ticket de suporte e um golpe na confiança independentemente de vocês terem duas contas enterprise ou duzentas.</p> <h2>FAQ</h2> <p><strong>Release notes privadas deveriam alguma vez mencionar funcionalidades que outras clientes já têm mas esta não?</strong> Só se for relevante para o cronograma dela própria, formulado como "chega na próxima atualização de vocês" em vez de como comparação com outras clientes. Nomear o que uma outra cliente específica tem cruza um território que não é de vocês para revelar; nomear o que chega especificamente para esta cliente é exatamente a informação de que ela precisa.</p> <p><strong>As mesmas entradas de changelog subjacentes podem alimentar tanto release notes públicas quanto privadas?</strong> Sim, e essa costuma ser a abordagem mais fácil de manter: marquem as entradas com quais versões ou níveis se aplicam, depois filtrem por audiência no momento da publicação em vez de escrever dois documentos completamente separados que inevitavelmente divergem.</p> <p><strong>E se uma cliente enterprise pedir explicitamente para estar nas release notes públicas em vez de em um feed privado?</strong> Respeitem isso, mas confirmem que ela entende que as notas públicas assumem a versão pública, e sinalizem vocês mesmos por escrito a lacuna se a versão dela divergir do que está descrito. Essa confirmação escrita é o que protege vocês depois se ela agir com base em notas públicas que na verdade não se aplicavam ao build dela.</p> <p><strong>Com quanto tempo de antecedência uma cliente enterprise deveria ser informada sobre uma funcionalidade à qual ela terá acesso na próxima release?</strong> Assim que a data for confirmada, não só no momento da release, porque administradoras enterprise frequentemente precisam planejar a própria comunicação interna ou treinamento em torno de uma funcionalidade que está chegando, e uma notificação no mesmo dia não deixa espaço para isso.</p> </article> <article> <h1>Semantic versioning e o seu changelog</h1> <p>Mon, 07 Sep 2026 00:00:00 GMT</p> <p>Semantic versioning diz a quem chama quanto um lançamento pode doer antes que ela leia uma única entrada do changelog. Ir de <code>2.4.1</code> para <code>2.5.0</code> diz: capacidade nova, nada quebra. Ir de <code>2.5.0</code> para <code>3.0.0</code> diz: leia essa entrada antes de atualizar. Changelog e número de versão deveriam afirmar a mesma coisa em dois formatos, e a maior parte do atrito entre eles aparece exatamente quando eles não concordam, o que acontece mais frequentemente do que a especificação sugeriria.</p> <h2>O que cada número em uma versão realmente promete?</h2> <p><a href="https://semver.org/">Semantic versioning</a> define três números, <code>MAJOR.MINOR.PATCH</code>, cada um com uma regra estrita sobre o que o dispara. Um salto MAJOR significa uma mudança incompatível: algo que uma integração correta e existente poderia notar e por causa da qual precisaria mudar. Um salto MINOR significa nova funcionalidade compatível com versões anteriores: nada existente quebra, algo novo fica disponível. Um salto PATCH significa uma correção compatível com versões anteriores: o comportamento se aproxima do que estava documentado, e ninguém que dependia de propósito do comportamento antigo deveria notar nada.</p> <table> <thead> <tr> <th>Salto</th> <th>Significado</th> <th>A entrada deveria soar como</th> </tr> </thead> <tbody><tr> <td>MAJOR (<code>1.x.x</code> -> <code>2.0.0</code>)</td> <td>Uma mudança incompatível</td> <td>"Precisa de ação antes de atualizar"</td> </tr> <tr> <td>MINOR (<code>1.2.x</code> -> <code>1.3.0</code>)</td> <td>Nova capacidade compatível</td> <td>"Já está disponível, nada mais mudou"</td> </tr> <tr> <td>PATCH (<code>1.2.3</code> -> <code>1.2.4</code>)</td> <td>Uma correção compatível</td> <td>"Agora se comporta como estava documentado"</td> </tr> </tbody></table> <p>A tabela também é um teste ao contrário: se uma entrada não lê como sua linha, ou o número de versão está errado, ou a entrada está subvendendo ou supervendendo o que realmente aconteceu.</p> <h2>O que conta como incompatível para fins de versionamento?</h2> <p>O mesmo teste que decide se algo pertence a um changelog de API: se quem chama corretamente, escrito contra o comportamento antigo e não tocado desde então, poderia se comportar diferente por causa dessa mudança. <a href="https://changeloop.dev/blog/pt-br/breaking-changes/">O que é uma mudança incompatível, e como lançá-la</a> cobre a decisão por completo, incluindo casos que parecem incompatíveis e não são, e os que parecem pequenos e não são. Resumindo para fins de versionamento: se a resposta é sim, o salto é MAJOR independentemente de quanto código a mudança realmente tocou internamente. Números de versão acompanham a consequência para quem chama, não o esforço do time.</p> <h2>Como uma entrada de changelog deveria corresponder a um salto de versão?</h2> <p>Uma entrada, uma categoria de salto, dita logo de cara. O padrão da tabela continua diretamente: uma entrada incompatível fica sob a versão que a introduziu, formulada primeiro como um aviso e depois como uma descrição. Uma entrada aditiva fica sob sua versão MINOR, formulada como disponibilidade. Uma correção fica sob sua versão PATCH, formulada como uma correção. Misturar categorias em uma entrada, como dobrar uma mudança incompatível no mesmo parágrafo de uma correção sem relação, é como uma leitora acaba perdendo exatamente a única coisa que realmente importava.</p> <pre><code>## 3.0.0 (2026-09-07) ### Changed - **BREAKING:** `GET /reports` agora retorna valores como inteiros na menor unidade monetária (centavos) em vez de decimais. Atualize qualquer código que leia `amount` diretamente. ## 2.9.0 (2026-09-01) ### Added - Relatórios agora podem ser filtrados por `status`. ## 2.8.4 (2026-08-28) ### Fixed - `GET /reports?status=` retornava uma página vazia em vez de um 400 para um status desconhecido. </code></pre> <p>Lido de cima para baixo, o número de versão e a etiqueta da seção dizem a mesma coisa duas vezes, e é exatamente esse o objetivo: uma leitora que só passa os olhos pelos títulos já tem uma leitura correta do risco antes de abrir uma única linha.</p> <h2>A regra de mudança incompatível vale do mesmo jeito antes de 1.0.0?</h2> <p>Não, e é daí que vem a maior parte da confusão sobre "isso era mesmo incompatível". O SemVer é explícito que a versão major zero, <code>0.y.z</code>, é para desenvolvimento inicial: qualquer coisa pode mudar a qualquer momento, e a API pública não deveria ser considerada estável. Um salto de <code>0.4.0</code> para <code>0.5.0</code> pode carregar uma mudança incompatível sem violar a spec, porque a garantia de versão major só começa quando um projeto lança <code>1.0.0</code>. Uma entrada de changelog ainda deve à leitora a mesma honestidade sobre o que quebrou; o que muda é só que o número de versão em si não é o sinal em que se apoiar antes de 1.0.0 chegar.</p> <h2>E se o seu produto não lança versões discretas?</h2> <p>A maioria dos produtos SaaS faz deploy contínuo e nunca mostra um número de versão a quem chama, o que não elimina a necessidade dessa disciplina, só o número que normalmente a carregaria. A entrada de changelog precisa fazer todo o trabalho sozinha: dizer claramente se uma mudança é incompatível, aditiva, ou uma correção, com as mesmas três palavras que semantic versioning usa, mesmo sem um campo de versão para anexá-las. Alguns times mantêm uma versão puramente interna só para ancorar entradas de changelog a algo que pode ser linkado, sem nunca mostrá-la diretamente a quem chama.</p> <h2>Como isso se aplica especificamente a um changelog de API?</h2> <p>De forma mais estrita do que quase em qualquer outro lugar, porque quem chama uma API é código, não pessoas que podem dar de ombros para uma mudança inesperada. <a href="https://changeloop.dev/blog/pt-br/api-changelog/">Changelog de API: o que publicar e quem lê</a> cobre a forma completa desse documento; a disciplina de versionamento aqui é o que mantém honestas suas seções breaking e aditivas. Uma API que oferece várias versões ao mesmo tempo, como <code>v1</code> e <code>v2</code> servidas em paralelo durante uma janela de migração, está efetivamente aplicando semantic versioning na escala de toda a interface em vez de um único pacote, e o mesmo vocabulário de três palavras ainda se aplica a cada entrada.</p> <h2>O que o Keep a Changelog diz sobre versionamento?</h2> <p>Ele se conecta diretamente pelo nome ao semantic versioning e recomenda o mesmo vocabulário de categorias que este artigo usa: Added, Changed, Deprecated, Removed, Fixed, Security. <a href="https://changeloop.dev/blog/pt-br/keep-a-changelog-implemented/">Keep a Changelog, na prática</a> percorre como adotar essa especificação, incluindo onde os times costumam se desviar dela. A sobreposição não é coincidência: as duas especificações tentam resolver o mesmo problema de pontas opostas, uma padroniza o número de versão e a outra a entrada que o explica.</p> <h2>FAQ</h2> <p><strong>Toda entrada de changelog precisa de um número de versão?</strong> Se o produto lança versões, sim, porque o número permite que uma leitora pule direto para "o quanto isso me afeta" sem ler a entrada primeiro. Se o produto faz deploy contínuo sem campo de versão, a formulação da entrada precisa carregar esse sinal sozinha.</p> <p><strong>Qual é a diferença entre um salto MAJOR e uma entrada de mudança incompatível?</strong> Eles deveriam descrever o mesmo evento de duas formas. O número de versão é o sinal legível por máquina (as ferramentas de quem chama podem reagir a ele); a entrada de changelog é a explicação legível por humanos do que exatamente mudou.</p> <p><strong>Um lançamento PATCH pode ser incompatível?</strong> Por definição, não deveria. Se um saiu mesmo assim, não editem nem refaçam a tag da versão publicada: a <a href="https://semver.org/#what-do-i-do-if-i-accidentally-release-a-backward-incompatible-change-as-a-minor-version">FAQ do SemVer</a> diz para lançar uma nova versão que restaure a compatibilidade, ou uma nova MAJOR se a quebra continuar, e documentar a versão problemática para que os usuários saibam que devem pulá-la.</p> <p><strong>Mudanças puramente internas precisam de um salto de versão?</strong> Não. Semantic versioning acompanha a interface pública. Uma refatoração sem efeito observável para quem chama não precisa nem de salto nem de entrada de changelog, mesmo que internamente tenha sido um trabalho de engenharia significativo.</p> </article> <article> <h1>Changelogs de webhook: o breaking change que ninguém pediu</h1> <p>Mon, 07 Sep 2026 00:00:00 GMT</p> <p>Um changelog de API REST existe porque quem chama pode escolher rejeitar uma resposta que não entende, ou pelo menos registrar um erro alto o suficiente para alguém notar. Um receptor de webhook raramente faz uma coisa ou outra. Ele recebe um POST, lê os campos que espera, e se um campo se moveu, mudou de tipo ou sumiu, o endpoint ou trava em silêncio dentro de um job em segundo plano que ninguém observa ou, pior, continua rodando com um valor errado que nunca validou. <a href="https://changeloop.dev/blog/pt-br/breaking-changes/">O que é um breaking change</a> cobre a definição geral; um payload de webhook precisa da própria resposta, porque o jeito de falhar é diferente do de um endpoint que alguém chama de propósito.</p> <h2>Por que uma mudança no payload de um webhook quebra diferente de uma mudança na resposta de uma API?</h2> <p>Porque a direção da requisição está invertida. Quem chama via REST inicia a chamada e pode adicionar um cabeçalho de versão, tentar de novo em um 4xx, ou ler um aviso de descontinuação na resposta. Um receptor de webhook não iniciou nada disso: seu servidor decidiu enviar, decidiu quando, e decidiu que forma o corpo teria. A única alavanca do receptor é a validação que ele escreveu quando a integração foi construída, e a maioria das integrações são construídas uma vez, funcionam, e ninguém revisita até quebrarem. Essa assimetria é o motivo inteiro pelo qual uma mudança no payload de um webhook merece mais cautela do que a mesma mudança em um corpo de resposta que quem chama pediu ativamente.</p> <h2>O que realmente conta como breaking change em um payload de webhook?</h2> <table> <thead> <tr> <th>Mudança</th> <th>Quebra para a maioria dos receptores</th> </tr> </thead> <tbody><tr> <td>Adicionar um campo novo</td> <td>Não, se os receptores ignoram campos desconhecidos (verifique essa suposição, não assuma)</td> </tr> <tr> <td>Remover um campo</td> <td>Sim, se algo o lê</td> </tr> <tr> <td>Renomear um campo</td> <td>Sim, funcionalmente idêntico a remover o antigo</td> </tr> <tr> <td>Mudar o tipo de um campo (string para objeto)</td> <td>Sim, quase sempre</td> </tr> <tr> <td>Reordenar campos no corpo JSON</td> <td>Não, para qualquer receptor que faz parse por chave, o que deveriam ser todos</td> </tr> <tr> <td>Mudar o nome ou tipo do evento</td> <td>Sim, se os receptores filtram ou roteiam com base nisso</td> </tr> </tbody></table> <p>A linha "adicionar um campo é seguro" é a que os times mais confiam e a que mais vale a pena verificar em vez de assumir. Um parser JSON permissivo ignora campos desconhecidos por padrão, mas um receptor que faz deserialize para um esquema estrito, várias linguagens tipadas fazem isso sem configuração extra, pode rejeitar o payload inteiro assim que um campo inesperado aparece. Adicionar um campo só é seguro para seu webhook se você souber como os receptores fazem parse, não porque o JSON em si é permissivo.</p> <h2>Como versionar um payload de webhook?</h2> <p>Mais ou menos como para uma resposta de API, com uma diferença: o receptor nunca envia uma requisição, então não pode pedir uma versão, e quem envia precisa declará-la. Ela pode ir no corpo ou em um cabeçalho da própria requisição de entrega; as <a href="https://docs.github.com/en/webhooks/webhook-events-and-payloads">entregas do GitHub</a> carregam <code>X-GitHub-Event</code> e <code>X-GitHub-Hook-ID</code>, e a <a href="https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md">especificação Standard Webhooks</a> coloca seus metadados em cabeçalhos <code>webhook-*</code>. Um campo de versão no payload (<code>"payload_version": 2</code>) é a opção mais barata e funciona quando os receptores estão dispostos a ramificar com base nele. Um tipo de evento versionado (<code>invoice.updated</code> vira <code>invoice.updated.v2</code> como um evento distinto ao qual um receptor se inscreve voluntariamente) exige mais trabalho para construir mas significa que a forma antiga continua chegando para quem nunca migrou, o que importa mais aqui do que em um endpoint REST porque você não pode ligar para cada receptor pedindo para atualizar. Uma configuração por assinatura, escolhida no registro do endpoint do webhook, antecipa a decisão em vez de ramificar a cada entrega, e é a escolha certa quando você já tem um registro de assinatura para anexá-la.</p> <pre><code>POST /endpoint-do-receptor { "event": "invoice.updated", "payload_version": 2, "data": { "invoice_id": "inv_123", "status": "paid" } } </code></pre> <h2>Como você sabe sequer quem está escutando?</h2> <p>Pior do que a versão equivalente desse problema em um changelog de API, porque um webhook não tem um log de requisições recebidas do seu lado que nomeie quem chama; você só tem seu próprio log de entrega enviada, que diz que um endpoint recebeu um 200, não o que ele fez com o corpo. Rastreie pelo menos duas coisas: cada endpoint registrado com uma dona, a mesma disciplina que <a href="https://changeloop.dev/blog/pt-br/internal-api-changelog/">changelogs de API interna</a> recomendam para consumidores internos, e sua taxa de falha de entrega por endpoint depois de uma mudança de payload. Um pico de respostas 4xx ou 5xx de um endpoint logo depois de uma mudança é a coisa mais próxima de um stack trace que você vai conseguir, e muitas vezes é o único sinal de que um receptor quebrou, porque o time que o opera pode não perceber por dias.</p> <h2>Um changelog de webhook deveria ser separado do changelog de API?</h2> <p>Uma seção separada na mesma página, não uma publicação separada. <a href="https://changeloop.dev/blog/pt-br/api-changelog/">Um changelog de API</a> já estabelece quem o lê e como se inscrever; uma mudança no payload de webhook pertence ao mesmo feed, etiquetada de forma clara o suficiente para que uma desenvolvedora do lado do receptor, escaneando por "isso afeta minha integração", consiga filtrar por ela, porque quem consome webhook muitas vezes não tem outro motivo para checar um changelog geral de API e só vai encontrá-lo se alguém a direcionar até lá diretamente.</p> <h2>Como deveria ser uma janela de descontinuação razoável para um payload de webhook?</h2> <p>Mais longa que a descontinuação REST equivalente, porque a migração do lado do receptor geralmente significa que um segundo time, com quem talvez você não tenha contato direto, precisa notar, planejar e lançar sem urgência própria. Um mês é um mínimo razoável para um campo que o receptor plausivelmente ainda faz parse com uma biblioteca permissiva; três meses ou mais são mais seguros para remover um campo que um esquema estrito rejeitaria completamente. Envie a forma antiga e a nova juntas durante a janela quando for viável (o campo antigo <code>status</code> e seu substituto da versão 2 no mesmo payload), porque um receptor que lê o campo antigo continua funcionando sem tocar no código, e um que já migrou simplesmente ignora o campo de que não precisa mais.</p> <h2>FAQ</h2> <p><strong>Consumidores de webhook precisam confirmar uma mudança de payload antes dela entrar no ar?</strong> Não existe mecanismo de confirmação por padrão, e é exatamente por isso que a janela de descontinuação importa mais aqui do que em uma API REST: ninguém confirma que está pronto, então a janela precisa ser longa o suficiente para que a maioria dos receptores migre no próprio ritmo antes da forma antiga desaparecer.</p> <p><strong>É sempre seguro adicionar campos desconhecidos sem aviso?</strong> Só depois de verificar, não assumir, que seus receptores fazem parse de forma permissiva. Uma entrada de changelog custa pouco e tira a incerteza; adicionar campos em silêncio na suposição de que "parsers JSON ignoram extras" quebra qualquer receptor com deserialização estrita.</p> <p><strong>Qual é o jeito mais rápido de detectar um receptor de webhook quebrado depois de uma mudança de payload?</strong> Uma taxa de falha de entrega por endpoint, observada nas horas logo depois da mudança. Ela não vai dizer o que quebrou, só que algo quebrou, mas é o sinal mais cedo e muitas vezes o único que você vai conseguir.</p> <p><strong>Lógica de retry ajuda receptores a sobreviver a uma mudança de payload?</strong> Não. Um retry reenvia o mesmo payload novo; ele não volta para uma forma que o receptor consiga fazer parse. Uma mudança de payload quebra um receptor na primeira entrega e em cada retry seguinte da mesma forma.</p> </article> <article> <h1>O header Sunset da API, e quando enviar um</h1> <p>Mon, 07 Sep 2026 00:00:00 GMT</p> <p><code>Sunset</code> é um único header de resposta, definido na <a href="https://www.rfc-editor.org/rfc/rfc8594">RFC 8594</a>, que diz a um chamador quando um recurso vai parar de responder. <a href="https://changeloop.dev/blog/pt-br/api-deprecation/">Depreciação de API</a> cobre o cronograma completo de anunciar-lembrar-brownout-aposentar e os avisos que o acompanham; isto é sobre o único sinal legível por máquina nesse cronograma, o que ele realmente diz, e o único caso em que a própria RFC diz para não enviá-lo.</p> <h2>O que o header Sunset diz, e o que ele não diz?</h2> <p>Ele carrega uma única HTTP-date, o ponto em que se espera que o recurso pare de responder:</p> <pre><code>Sunset: Sat, 31 Dec 2028 23:59:59 GMT </code></pre> <p>A RFC o chama de uma dica, não uma garantia: ela não promete que o recurso vai continuar funcionando até esse timestamp, e não diz nada sobre como vai ser a falha depois. O chamador pode receber um 4xx, um redirecionamento, ou nenhuma resposta; o header não diferencia. Um timestamp já no passado significa "agora, ou a qualquer momento", não um erro no valor. Nada disso é imposto pelo protocolo. Um cliente que nunca lê o header se comporta exatamente como sempre se comportou, e descobre que o recurso sumiu do mesmo jeito que descobriria de qualquer forma.</p> <h2>Quando vale a pena realmente enviá-lo?</h2> <p>Só quando o recurso realmente vai parar de responder, não enquanto ele é apenas a opção não mais recomendada. A RFC é explícita: a depreciação acontece em dois estágios, e o campo Sunset pertence só ao segundo. A API continua totalmente operacional durante o primeiro estágio, o anúncio de que uma versão não é mais a preferida, e o campo não se aplica ali. Ele se aplica quando a versão está realmente programada para parar de responder.</p> <p>Isso mapeia direto para o cronograma de depreciação: o header <code>Deprecation</code> sai desde o primeiro dia, na etapa de anúncio; <code>Sunset</code> descreve a data em que o comportamento antigo realmente vai parar, a mesma data que <a href="https://changeloop.dev/blog/pt-br/api-deprecation/">o cronograma de quatro etapas</a> chama de aposentadoria. Enviar <code>Sunset</code> no primeiro dia não é errado, já que a data já está fixada nesse ponto, mas enviá-lo sem ter anunciado uma depreciação, ou fixá-lo para uma versão que vocês ainda não se comprometeram a aposentar, diz aos chamadores algo que vocês ainda não decidiram.</p> <h2>Ele interage com cache?</h2> <p>Não, e a RFC diz isso diretamente: <code>Sunset</code> e o cache HTTP resolvem problemas não relacionados e devem ser lidos como complementares, não sobrepostos. Os headers de cache dizem quando uma cópia em cache é segura para reutilizar; <code>Sunset</code> não diz nada sobre o estado atual do recurso, só que o recurso em si vai deixar de existir. Uma resposta pode ser totalmente cacheável até o exato momento em que ela expira pelo sunset. Não usem um para aproximar o outro, e não assumam que um <code>max-age</code> longo anula uma data de sunset se aproximando, nem o contrário.</p> <h2>Um único header pode encerrar mais de um endpoint?</h2> <p>O header se aplica ao recurso que o retornou, mas a RFC permite que um serviço documente um escopo mais amplo: uma data de Sunset no recurso raiz de uma API pode ser definida para significar que a API inteira vai sair do ar, não só aquela URL. A pegadinha é que isso só funciona para chamadores que já conhecem a regra de escopo de vocês. Um chamador lendo o header ao pé da letra vê um sunset no único recurso que pediu e nada mais, então um escopo mais amplo precisa estar escrito em algum lugar que o chamador consiga encontrar, não apenas implícito.</p> <h2>O que deveria acompanhar o header?</h2> <p>Um link para onde a aposentadoria é explicada. A RFC 8594 registra sua própria relação de link <code>sunset</code> exatamente para isso: apontar para um recurso que descreve a política de aposentadoria, a data que se aproxima, ou como migrar, separado do timestamp puro do header.</p> <pre><code>HTTP/1.1 200 OK Sunset: Sat, 31 Dec 2028 23:59:59 GMT Link: <https://example.com/docs/sunset-policy>; rel="sunset" </code></pre> <p>Apontar esse link para os próprios <a href="https://changeloop.dev/changelog-examples">exemplos de changelog</a> de vocês, ou para uma página de migração dedicada, transforma um header que quase nenhum código de cliente inspeciona em algo que um humano que vai procurar encontra imediatamente. Combinem isso com a relação <code>successor-version</code> vinda de <a href="https://changeloop.dev/blog/pt-br/api-deprecation/#which-headers-should-a-deprecated-endpoint-send">os headers de depreciação</a> e o chamador recebe, só pela resposta, tanto para onde ir quanto o que substitui esta versão.</p> <h2>Como isso fica na prática, do início ao fim?</h2> <p>Digamos que <code>v1</code> vai sair do ar em 1º de março de 2027. O anúncio de depreciação no primeiro dia adiciona <code>Deprecation</code> e <code>Link: rel="successor-version"</code> a toda resposta <code>v1</code>, conforme <a href="https://changeloop.dev/blog/pt-br/api-deprecation/">os headers de depreciação</a>, mas segura o <code>Sunset</code> até que a data de aposentadoria esteja realmente fixada, em vez de ser um placeholder. Uma vez que esteja, toda resposta <code>v1</code> carrega:</p> <pre><code>HTTP/1.1 200 OK Deprecation: @1756425600 Sunset: Mon, 01 Mar 2027 00:00:00 GMT Link: <https://api.example.com/v2/reports>; rel="successor-version" Link: <https://example.com/docs/sunset-policy>; rel="sunset" </code></pre> <p>O gateway ou o monitoramento do chamador pode alertar em cada header de forma independente: <code>Deprecation</code> diz que existe uma versão mais nova, <code>Sunset</code> diz que esta tem um prazo correndo. Nenhum dos dois headers precisa mudar antes de 1º de março; o que muda é a própria resposta, no dia, e durante qualquer janela de brownout agendada antes dele.</p> <h2>Um brownout muda o que o header diz?</h2> <p>O valor do header em si não precisa mudar por causa de um brownout agendado: a data de sunset continua sendo a data de sunset, quer o recurso esteja falhando intermitentemente antes dela ou não. O que muda é a resposta, não o header. Agendar janelas curtas de <code>410 Gone</code> nas semanas antes da data anunciada, como <a href="https://changeloop.dev/blog/pt-br/api-deprecation/">Depreciação de API</a> descreve, é o que transforma o primeiro contato do chamador com a falha em um ensaio, em vez do evento real no dia em que a data do header chega.</p> <h2>FAQ</h2> <p><strong>Algum cliente HTTP ou ferramenta real realmente lê o header Sunset?</strong> Raramente, do lado do cliente. O valor dele é sobretudo para quem opera a infraestrutura entre vocês e o chamador: um gateway de API ou uma ferramenta de monitoramento que vocês configuram para vigiar o header pode alertar a própria equipe de vocês, ou a de um parceiro, bem antes que o código do chamador chegue a notar. Tratem isso como um sinal ao redor do qual vocês constroem ferramentas, não um que já podem supor que o outro lado tem.</p> <p><strong><code>Sunset</code> é a mesma coisa que <code>Cache-Control: max-age</code>?</strong> Não. <code>max-age</code> é sobre por quanto tempo uma cópia em cache continua válida; <code>Sunset</code> é sobre quando o recurso deixa de existir de vez. Uma resposta pode carregar um <code>max-age</code> curto e uma data de <code>Sunset</code> anos à frente, ou o contrário, e nenhum dos dois headers limita o outro.</p> <p><strong>Posso enviar Sunset para um único campo que vai sumir, e não o endpoint inteiro?</strong> Não, o header tem escopo no recurso, ou seja, na URL, não em um campo dentro do corpo da resposta. Para um campo, um parâmetro ou um valor de enum que vai sumir enquanto o endpoint em si continua no ar, usem o header <code>Deprecation</code> e uma entrada de changelog em vez disso; <a href="https://changeloop.dev/blog/pt-br/api-deprecation/">Depreciação de API</a> cobre exatamente como anunciar esse tipo de mudança.</p> <p><strong>E se a data de sunset precisar mudar?</strong> Atualizem o valor do header e digam isso na entrada de changelog que a anunciou originalmente; mudar uma data publicada em silêncio é como um chamador decide que nenhuma das datas de vocês é real. A RFC enquadra o valor como uma dica exatamente porque datas às vezes mudam, mas uma data movida sem explicação custa a próxima também.</p> </article> <article> <h1>Changelog: o que é, com um exemplo de entrada</h1> <p>Mon, 07 Sep 2026 00:00:00 GMT</p> <p>Um changelog é o registro datado do que mudou em um produto, escrito para as pessoas afetadas pela mudança, não para o time que a lançou. Cada entrada nomeia uma mudança, diz quando ela entrou em vigor, e diz o que a leitora deve fazer a respeito, o que na maioria das entradas significa nada. É essa última parte que separa um changelog de um log de commits: um log de commits é um registro para quem escreveu o código, um changelog é um registro para quem o usa.</p> <h2>O que é um changelog, exatamente?</h2> <p>Uma lista de entradas datadas, da mais recente para a mais antiga, cada uma descrevendo uma única mudança em termos que a leitora consegue verificar. Não o que o time construiu, mas o que agora é diferente. "Refatoração do serviço de faturamento" é uma mensagem de commit. "As faturas agora mostram o imposto como uma linha separada" é uma entrada de changelog, porque diz à leitora algo que ela pode conferir na própria conta.</p> <p>O formato é antigo e deliberadamente simples: um título por lançamento ou por dia, uma lista curta abaixo, às vezes uma etiqueta de categoria. <a href="https://keepachangelog.com/en/1.1.0/">Keep a Changelog</a> é a especificação mais citada para essa forma, e existe porque a maioria dos projetos que pulam uma especificação acabam despejando o histórico de commits no lugar dela, o que responde a uma pergunta diferente daquela com a qual a leitora chegou.</p> <table> <thead> <tr> <th>Documento</th> <th>Escrito para</th> <th>Responde</th> </tr> </thead> <tbody><tr> <td>Changelog</td> <td>Quem usa o produto</td> <td>O que mudou, e quando?</td> </tr> <tr> <td>Log de commits</td> <td>O time que escreveu o código</td> <td>O que foi feito, em que ordem?</td> </tr> <tr> <td>Notas de versão</td> <td>Usuárias decidindo se atualizam</td> <td>O que posso fazer agora que não podia?</td> </tr> <tr> <td>Notas de patch</td> <td>Jogadoras ou usuárias de um fix específico</td> <td>O que exatamente esse lançamento corrigiu?</td> </tr> <tr> <td>Roadmap</td> <td>Quem se pergunta o que vem a seguir</td> <td>O que está planejado, e em que ponto está?</td> </tr> </tbody></table> <p>Os cinco se sobrepõem na prática, mas não são o mesmo documento, e a diferença está em quem o segura na mão no momento de ler. Um changelog é o que foi construído para ser buscado e linkado de novo depois, por isso suas entradas precisam de datas e URLs estáveis mais do que os outros.</p> <h2>O que uma entrada de changelog realmente contém?</h2> <p>Quatro coisas, nesta ordem: o que mudou, formulado nos termos que a usuária ou a parte chamadora notaria; quando entrou em vigor; a qual categoria pertence (added, fixed, changed, removed são as quatro comuns); e, quando importa, o que a leitora deve fazer a respeito. Um link para mais detalhes é bem-vindo. Um parágrafo de justificativa interna não é, porque a leitora não perguntou por quê, perguntou o quê.</p> <pre><code>## 2026-09-07 ### Added - As faturas agora mostram o imposto como uma linha separada, na moeda da conta do cliente. ### Fixed - Exportar um relatório como CSV não perde mais a última linha quando o relatório passa de 10.000 linhas. </code></pre> <p>Essa forma escala de uma atualização de duas linhas até cem entradas em um único lançamento sem mudar de estrutura, e esse é o verdadeiro teste de se um formato funciona: se ele lê da mesma forma numa semana cheia e numa semana tranquila.</p> <h2>Quem escreve um changelog, e quando?</h2> <p>Quem fez a mudança, no momento em que ela é lançada, não uma redatora técnica reconstruindo-a a partir de tickets uma semana depois. Quem mexeu no código sabe o que realmente mudou para a usuária; um resumo escrito depois tende a descrever o ticket em vez do que de fato foi lançado, e isso costuma ser mais amplo ou mais estreito que o escopo real. Alguns times adicionam uma etapa de revisão antes de uma entrada se tornar pública, principalmente para pegar linguagem interna que vazou, e essa revisão precisa ser rápida o suficiente para a entrada sair no mesmo dia.</p> <h2>Onde um changelog deveria viver?</h2> <p>Na própria página, em uma URL estável, distribuído como feed. Enterrado em um menu de configurações ou em uma tag de lançamento em um hospedeiro de código, ele só alcança quem já sabia onde procurar. Uma página pública pode ser linkada a partir de um ticket de suporte, citada em uma resenha, ou assinada. O feed importa tanto quanto a página: uma leitora que checa o changelog de um produto uma vez por mês é rara, uma que o assina não é, e só o feed atende a esse segundo grupo.</p> <h2>Como ele difere das notas de versão?</h2> <p>Os dois são constantemente confundidos, e diferentes o suficiente para que misturá-los produza um documento que não serve bem a nenhuma das duas leitoras. <a href="https://changeloop.dev/blog/pt-br/changelog-vs-release-notes/">Changelog versus notas de versão</a> percorre a distinção por completo; resumindo, um changelog é o registro completo e cronológico, e as notas de versão são um subconjunto curado, escrito para que uma atualização soe como algo que vale a pena ter. Um produto geralmente precisa dos dois, direcionados a momentos diferentes do dia da leitora.</p> <h2>O que faz um changelog valer a pena ser lido?</h2> <p>Especificidade e honestidade sobre o próprio alcance. "Diversas correções de bugs" é a frase que ensina uma leitora a parar de abrir a página, porque não promete nada que ela possa verificar. Uma entrada que nomeia o comportamento exato que mudou, mesmo para uma correção pequena, é a que mantém uma assinatura viva. Essa disciplina também vale para o que se omite: um changelog que só anuncia vitórias e nunca uma correção para algo que estava quebrado se lê como marketing disfarçado de changelog, e as leitoras percebem isso.</p> <p>A disciplina de versionamento também importa. <a href="https://changeloop.dev/blog/pt-br/semantic-versioning-changelog/">Semantic versioning e o seu changelog</a> mostra como o número de versão e a entrada deveriam bater, para que uma leitora percorrendo o histórico de versões receba o mesmo sinal duas vezes em vez de dois sinais diferentes.</p> <h2>Como os changelogs são gerados?</h2> <p>De duas formas, e a maioria das configurações reais é uma mistura. A geração automatizada lê mensagens de commit, geralmente no formato <a href="https://www.conventionalcommits.org/en/v1.0.0/">Conventional Commits</a>, e as transforma em entradas sem que ninguém toque no resultado; <a href="https://changeloop.dev/blog/pt-br/conventional-commits-changelog/">de conventional commits a changelog</a> cobre esse pipeline. A geração curada significa que alguém escreve ou edita cada entrada manualmente. O resultado automatizado é mais rápido e nunca perde um pull request mesclado, mas herda cada mensagem de commit vaga ao pé da letra, então a maioria dos times que automatizam ainda mantém uma passada leve de edição antes de publicar, em vez de mostrar o resultado bruto.</p> <h2>FAQ</h2> <p><strong>Todo produto precisa de um changelog?</strong> Qualquer produto com usuárias afetadas pela mudança precisa de um, seja um app SaaS, uma ferramenta interna, ou uma API pública. A forma se adapta (um changelog de API se lê diferente do de um app de consumo), a necessidade não.</p> <p><strong>O que é um changelog em termos de software?</strong> A mesma definição de acima: uma lista datada e cronológica do que mudou no software, escrita para quem o usa, não para quem o construiu.</p> <p><strong>Um changelog pode ser gerado automaticamente a partir de commits?</strong> Sim, e muitos times fazem exatamente isso, geralmente a partir de mensagens no formato Conventional Commits. O trade-off é que uma entrada gerada é tão clara quanto a mensagem de commit de onde veio, então uma passada de revisão antes de publicar pega as que precisam ser reformuladas.</p> <p><strong>Um changelog é a mesma coisa que um histórico de versões?</strong> Próximo o suficiente para que os termos sejam usados de forma intercambiável. Um histórico de versões às vezes é só uma lista de números de versão e datas sem descrição; um changelog sempre inclui o que mudou.</p> </article> <article> <h1>Changelog de API: o que publicar e quem lê</h1> <p>Wed, 02 Sep 2026 00:00:00 GMT</p> <p>Um changelog de API é o registro datado de cada mudança que um chamador poderia notar, escrito para quem integra com a API, não para o time que a lança. Esse público é o que o torna um documento diferente de um changelog de produto: o leitor está decidindo se o próprio código vai continuar funcionando no mês seguinte. A maioria falha do mesmo jeito, sendo uma cópia filtrada de um feed interno de releases, de modo que um campo removido acaba ao lado de uma correção de texto com o mesmo peso, e nenhum dos dois é lido.</p> <h2>O que é um changelog de API?</h2> <p>É o registro público e datado de mudanças em uma interface contra a qual outras pessoas escreveram código. O teste útil para saber se algo pertence ali não tem nada a ver com o tamanho da mudança internamente. Ele pergunta se um chamador correto, escrito no ano passado e nunca mais tocado, poderia se comportar de forma diferente por causa dela. Esse teste admite algumas mudanças bem pequenas e exclui algumas bem grandes.</p> <p>Tudo abaixo assume que quem chama está fora da empresa e é efetivamente inalcançável a não ser por este documento. Quando quem chama é outro time da mesma empresa, a conta muda o suficiente para merecer um tratamento próprio; <a href="https://changeloop.dev/blog/pt-br/internal-api-changelog/">changelogs de API interna</a> cobre o que esse público precisa em vez disso.</p> <table> <thead> <tr> <th>Documento</th> <th>Público</th> <th>Responde</th> </tr> </thead> <tbody><tr> <td>Changelog de API</td> <td>Desenvolvedores que chamam a API</td> <td>Minha integração ainda funciona?</td> </tr> <tr> <td>Notas de versão</td> <td>Usuários do produto</td> <td>O que posso fazer agora que não podia antes?</td> </tr> <tr> <td>Aviso de depreciação</td> <td>Quem chama uma coisa específica</td> <td>Quando isso vai parar de funcionar?</td> </tr> <tr> <td>Página de status</td> <td>Qualquer um afetado agora</td> <td>Está fora do ar agora?</td> </tr> <tr> <td>Guia de migração</td> <td>Quem está atualizando</td> <td>Como eu passo de A para B?</td> </tr> </tbody></table> <p><a href="https://changeloop.dev/blog/pt-br/api-migration-guide/">Como escrever um guia de migração de API</a> cobre esse último documento por completo; resumindo, é para onde uma entrada de mudança incompatível deveria linkar, em vez de tentar substituí-lo.</p> <p>Os cinco são documentos separados com ciclos de vida separados. Um aviso de depreciação é uma promessa com data, e também pertence ao changelog, mas uma entrada de changelog é escrita uma vez, enquanto uma depreciação é acompanhada até seu sunset. Confundir os dois é o motivo pelo qual sunsets são perdidos.</p> <h2>O que deve entrar em uma única entrada?</h2> <p>Seis coisas, e as três primeiras são as que costumam faltar. A mudança em si, formulada em termos da requisição ou resposta, não do componente interno. Se ela quebra um chamador correto. O que o chamador precisa fazer, incluindo "nada". A data em que passou a valer. A versão ou versões afetadas. Um link para o guia de migração, quando existir.</p> <p>Uma entrada que diz "endpoint de accounts melhorado" falha em todas as seis. Uma entrada que diz "o campo <code>accounts.type</code> agora retorna <code>individual</code> onde antes retornava <code>personal</code>; valores existentes permanecem inalterados para contas criadas antes de 2 de setembro; nenhuma ação é necessária a menos que você compare a string" responde às seis em uma frase.</p> <p>Categorize as entradas por consequência, não por departamento. Três rótulos carregam quase todo o valor: breaking, additive e fixed. O <a href="https://semver.org/">Semantic Versioning</a> já define os dois primeiros com precisão, e emprestar suas definições em vez de inventar as próprias significa que um leitor que conhece semver conhece seus rótulos. O <a href="https://keepachangelog.com/en/1.1.0/">Keep a Changelog</a> oferece um conjunto mais longo se você quiser, e sua regra central se aplica aqui com mais força do que em qualquer outro lugar: o log é para humanos, e um despejo de títulos de commit não é.</p> <h2>Em que um changelog de API difere das notas de versão?</h2> <p>Notas de versão descrevem o que o produto consegue fazer agora. Um changelog de API descreve qual é o contrato agora. O mesmo trabalho lançado geralmente produz uma entrada nos dois, formulada de forma diferente, porque os públicos precisam de coisas diferentes: um novo formato de exportação é uma funcionalidade para um usuário e um novo valor de enum para um chamador que decide com base nesse campo.</p> <p>A consequência prática é que os dois não podem ser o mesmo feed com estilo diferente. Um chamador inscrito em tudo que você lança acaba se desinscrevendo, e então perde a mudança que quebra algo. Se você publica um feed, filtre-o; se publica dois, deixe o de API mais estreito e nunca deixe uma entrada de marketing entrar nele. Comparamos as duas formas lado a lado em <a href="https://changeloop.dev/blog/pt-br/changelog-vs-release-notes/">changelog vs notas de versão</a>.</p> <h2>Onde um changelog de API deve viver?</h2> <p>Ao lado da documentação de referência, em uma URL estável, com cada entrada endereçável individualmente por um fragmento ou caminho próprio. Chamadores linkam entradas em análises de incidentes e tickets internos, e uma entrada que não pode ser linkada acaba colada como print de tela em vez disso.</p> <p>Publique-o também como saída legível por máquina, além da página. Um feed JSON seguindo a <a href="https://www.jsonfeed.org/version/1.1/">especificação JSON Feed</a> ou um <a href="https://www.rssboard.org/rss-specification">feed RSS</a> não custa nada assim que as entradas viram dados estruturados, e é isso que permite que um cliente incorpore suas mudanças ao próprio processo de release. Essa é também a parte que decide se alguém constrói em cima disso. O GitHub documenta suas <a href="https://docs.github.com/en/rest/about-the-rest-api/api-versions">versões da REST API</a> bem ao lado da referência pelo mesmo motivo: a política de versionamento faz parte da interface.</p> <h2>Como é uma boa entrada na prática?</h2> <p>Três entradas da mesma semana, na forma descrita acima:</p> <pre><code>2026-09-02 Breaking v2 `POST /invoices` agora rejeita uma `currency` que não corresponde à moeda da conta do cliente, retornando 422 em vez de converter silenciosamente. Chamadores que dependiam da conversão precisam enviar a moeda da conta. Afeta apenas v2; v1 permanece inalterado até o sunset em 2027-01-15. 2026-09-02 Additive v1, v2 `Invoice` ganha um timestamp `settled_at`, nulo até a fatura ser quitada. Nenhuma ação necessária. Clientes que rejeitam campos desconhecidos devem ser atualizados. 2026-08-31 Fixed v2 `GET /invoices?status=` retornava uma página vazia em vez de um 400 para um status desconhecido. Agora retorna 400 com os valores aceitos. Chamadores com um erro de digitação antes viam zero resultados, agora veem um erro. </code></pre> <p>A terceira é o tipo mais frequentemente omitido, porque internamente é uma correção de bug. Para um chamador que construiu um retry em torno daquela página vazia, é uma mudança de comportamento, e a entrada é o que evita o ticket de suporte. O rótulo diz fixed e o corpo diz o que um chamador poderia notar, o que é a distinção que mantém o log honesto sem inflar cada correção para mudança que quebra algo.</p> <h2>Como os chamadores se inscrevem nisso?</h2> <p>Dê a eles mais de um canal, porque têm tarefas diferentes. Um feed para o desenvolvedor que quer tudo. E-mail para quem só quer mudanças que quebram algo. Cabeçalhos de resposta para o próprio código, o único assinante que nunca esquece de checar: o <a href="https://datatracker.ietf.org/doc/html/rfc8594">cabeçalho <code>Sunset</code> definido na RFC 8594</a> coloca a data de retirada na resposta, onde uma biblioteca cliente pode registrá-la.</p> <p>O canal que a maioria dos times pula é o direto. Se um chamador usou na semana passada o campo que você está mudando, você sabe quem é essa pessoa, e um e-mail para essas contas vale mais do que qualquer transmissão geral. É a mesma disciplina de <a href="https://changeloop.dev/blog/pt-br/customer-feedback-loop/">fechar o loop de feedback do cliente</a>, aplicada a uma mudança que ninguém pediu: as pessoas afetadas são avisadas individualmente, e todas as outras recebem o feed. Um webhook é um quarto canal com o próprio jeito de falhar que vale a pena conhecer antes de confiar nele: <a href="https://changeloop.dev/blog/pt-br/webhook-changelog/">changelogs de webhook</a> cobre por que uma mudança de payload ali quebra em silêncio, sem quem chame para rejeitar a nova forma.</p> <h2>Como escrever uma entrada para uma mudança que quebra algo?</h2> <p>Comece pela quebra, não pelo motivo. Um chamador escaneando dez entradas precisa saber na primeira frase se essa vai custar trabalho a ele. Depois a data, as versões afetadas, a migração, e o prazo final se o comportamento antigo está sumindo em vez de mudando.</p> <p>Coloque o mesmo conteúdo no aviso de depreciação, no cabeçalho de resposta e no e-mail direto, formulado de forma consistente, e dê aos quatro a mesma data. A divergência entre eles é a falha que transforma uma mudança planejada em um incidente, porque o chamador que leu só um deles age na data errada. <a href="https://changeloop.dev/blog/pt-br/breaking-changes/">O que é uma mudança que quebra algo</a> cobre a decisão em si, e <a href="https://changeloop.dev/blog/pt-br/api-deprecation/">como depreciar uma API</a> cobre o cronograma que vem depois.</p> <p>No changeloop, uma mudança de API se torna uma entrada quando o pull request é mesclado, alguém edita e aprova o rascunho, e a entrada é publicada no <a href="https://changeloop.dev/docs">feed e no widget</a> no mesmo momento em que um chamador cujo feedback pelo widget virou a issue do GitHub que o pull request fecha é avisado nessa issue. O passo de revisão é o que importa aqui: um changelog de API é um documento contratual, e nenhum rascunho deveria chegar a um chamador sem que uma pessoa o tivesse lido.</p> <h2>FAQ</h2> <p><strong>Toda mudança de API precisa de uma entrada de changelog?</strong> Toda mudança que um chamador correto poderia notar, sim, incluindo as que você considera internas. Mudanças sem efeito observável na requisição ou resposta não, e adicioná-las treina os leitores a passar os olhos rapidamente.</p> <p><strong>O changelog de API deveria viver na documentação ou no site de marketing?</strong> Na documentação, bem ao lado da referência. O leitor geralmente já está lá, e um changelog no site de marketing tende a ganhar um público para o qual não foi escrito.</p> <p><strong>Até quando ele deveria voltar no tempo?</strong> Indefinidamente. Entradas são citadas anos depois em análises de incidentes, e um log truncado quebra esses links. Pagine em vez de podar.</p> <p><strong>Preciso de um changelog separado por versão de API?</strong> Não, um único log com um campo de versão por entrada é mais fácil de ler e buscar. Filtrar por versão é uma funcionalidade da página, não um motivo para dividir o documento.</p> </article> <article> <h1>Uma página de changelog que as pessoas realmente acompanham</h1> <p>Wed, 02 Sep 2026 00:00:00 GMT</p> <p>Uma página de changelog vale a pena construir quando alguém voltaria a ela. Essa é uma régua mais alta do que simplesmente ter uma, e é a régua onde a maioria falha: uma página que existe, tem link no rodapé, é atualizada aos trancos e barrancos e não é visitada por ninguém exceto durante um incidente. As decisões que separam as duas são tomadas antes de qualquer coisa ser escrita, e são principalmente sobre onde a página vive e o que mais é gerado a partir do mesmo conteúdo.</p> <h2>O que é uma página de changelog?</h2> <p>É a lista pública e datada do que mudou em um produto, em uma URL que pertence a você. É uma de cinco superfícies onde as mesmas entradas podem aparecer, e a pergunta útil não é qual escolher, mas qual é canônica e quais são geradas a partir dela.</p> <table> <thead> <tr> <th>Superfície</th> <th>Melhor para</th> <th>Custo</th> </tr> </thead> <tbody><tr> <td>Página hospedada</td> <td>Busca, links, o registro longo</td> <td>Uma URL e um template</td> </tr> <tr> <td>Widget no app</td> <td>Alcançar usuários que nunca visitam a página</td> <td>Um embed, e contenção</td> </tr> <tr> <td>Seção de docs</td> <td>Público de API e desenvolvedores</td> <td>Mantê-lo ao lado da referência</td> </tr> <tr> <td>Feed JSON</td> <td>Clientes que constroem sobre suas mudanças</td> <td>Estrutura que você já tem</td> </tr> <tr> <td>Feed RSS</td> <td>Desenvolvedores que se inscrevem uma vez</td> <td>Quase nada</td> </tr> </tbody></table> <p>Escolha uma fonte canônica, publique uma vez, e gere o resto. Times que mantêm a página e o widget separadamente à mão acabam com dois textos que não batem, e a discrepância é descoberta por um cliente.</p> <h2>Onde uma página de changelog deve viver?</h2> <p>No seu próprio domínio, em um caminho estável, com cada entrada endereçável individualmente. Os três locais comuns são um caminho no site principal, um subdomínio, e uma seção da documentação. Um caminho no site principal é a escolha padrão contra a qual se deve argumentar, não a favor dela: herda a autoridade do site, não precisa de certificado ou DNS extra, e mantém a página na mesma navegação que tudo o mais.</p> <p>Um subdomínio é a resposta certa quando a página é servida por um sistema diferente do site de marketing e você faria proxy de outra forma. O custo é que ele acumula autoridade separadamente. Colocar o changelog na documentação é certo quando o público são desenvolvedores, pelo motivo coberto em <a href="https://changeloop.dev/blog/pt-br/api-changelog/">changelog de API</a>: o leitor geralmente já está lá.</p> <p>Mais importante do que a escolha é que as entradas possam ser linkadas individualmente. As pessoas linkam entradas em análises de incidentes e tickets internos, e uma entrada que só pode ser linkada como "o changelog, role para baixo" acaba colada como print de tela em vez disso.</p> <h2>O que uma página de changelog precisa?</h2> <p>Cinco coisas, e nas duas primeiras a maioria das páginas falha. Uma entrada datada por mudança, a mais recente primeiro. Uma categoria ou rótulo por entrada para poder escanear pelo tipo que interessa. Um link permanente por entrada. Uma rota de assinatura. Uma busca ou filtro depois de cerca de cinquenta entradas.</p> <p>O resto é opcional. Prints de tela ajudam e custam manutenção. Nomes de autores constroem confiança em alguns produtos e são ruído em outros. Números de versão importam para chamadores de uma API e para quase mais ninguém. O <a href="https://keepachangelog.com/en/1.1.0/">Keep a Changelog</a> é uma escolha padrão razoável para rótulos se você não tem motivo para inventar os próprios, e sua regra central é a que vale a pena manter mesmo que você descarte o resto: o log é escrito para pessoas.</p> <p>Agrupe por data, não por versão, quando seu produto lança continuamente. Um leitor escaneando "isso foi antes ou depois do nosso incidente do dia nove" está procurando uma data, e uma página organizada por número de versão o obriga a fazer contas.</p> <h2>Página ou widget no app?</h2> <p>Os dois, de uma única fonte. A página é onde vivem a busca, os links e o registro longo. O widget é como você alcança a maioria dos usuários que nunca vão visitar a página, e funciona porque aparece no produto que eles já usam.</p> <p>O fracasso do widget é a interrupção. Um badge que exige atenção para cada entrada é descartado permanentemente em uma semana, o que custa a você o canal para a entrada que realmente importava. Conte não lidas desde a última vez que o leitor olhou, plante o contador silenciosamente na primeira visita para que ninguém seja recebido com um badge de um ano de histórico, e deixe o leitor abri-lo em vez de abrir para ele.</p> <h2>Como tornar uma página de changelog legível por máquina?</h2> <p>Publique as mesmas entradas como feed. Um <a href="https://www.jsonfeed.org/version/1.1/">feed JSON</a> é a opção de menor atrito para qualquer coisa que o consuma em código, e um <a href="https://www.rssboard.org/rss-specification">feed RSS</a> é o que um desenvolvedor assinando em um leitor espera. Os dois custam pouco assim que as entradas são dados estruturados em vez de HTML escrito à mão, o que é o argumento real para manter a cópia canônica estruturada.</p> <p>Marque a página também. Entradas são obras com data e título, e o <a href="https://schema.org/CreativeWork">schema.org</a> fornece o vocabulário. Vale a pena pelo mesmo motivo dos links permanentes: torna a página utilizável por coisas que não são um navegador, incluindo o próprio processo de release de um cliente. Nada disso funciona se as entradas subjacentes nunca foram dados estruturados desde o início; <a href="https://changeloop.dev/blog/pt-br/changelog-file-formats/">formatos de arquivo de changelog</a> cobre quanto custa cada um entre Markdown, JSON e YAML como a fonte de verdade da qual esse feed e essa marcação são de fato gerados.</p> <h2>Uma página de changelog ajuda o SEO?</h2> <p>Indiretamente e devagar. Entradas individuais raramente rankeiam, porque não miram em nenhuma busca que alguém digita. A página ganha seu lugar através de links: entradas são citadas em respostas de suporte, fóruns e análises de incidentes, e esses links se acumulam em uma URL que pertence a você. Uma página atualizada semanalmente por dois anos também é um sinal de frescor confiável para o produto ao qual pertence.</p> <p>O que não funciona é tratar entradas como marketing de conteúdo. Uma entrada inflada para três parágrafos por causa do tamanho fica pior no seu trabalho real, que é dizer ao leitor em uma frase se algo que ele usa mudou. Se você quer que o changelog apoie a busca, coloque o esforço nos links permanentes, no feed e nos links internos para ele, e mantenha as entradas curtas. Nossa própria página de <a href="https://changeloop.dev/changelog-examples">exemplos de changelog</a> reúne páginas que acertam esse equilíbrio.</p> <h2>Como as pessoas se inscrevem?</h2> <p>Dê a elas as rotas que já usam: um feed RSS ou JSON para desenvolvedores, e-mail para quem só quer ouvir as coisas importantes, e o widget no app para todos que nunca vão fazer nenhum dos dois. Pergunte o que elas querem ouvir em vez de assumir, porque um leitor que quer mudanças que quebram algo e recebe correções de texto se desinscreve dos dois.</p> <p>A rota que vale a pena adicionar por último é a que fecha o loop. Quando uma entrada resolve algo que uma pessoa específica pediu, diga a ela diretamente, em vez de esperar que leia a página. No changeloop, a entrada é publicada de uma vez na <a href="https://changeloop.dev/docs">página, no feed e no widget</a>, e uma pessoa cujo feedback pelo widget virou a issue do GitHub que o pull request fechou é avisada nessa issue, com um link para a entrada, e vê a entrada no widget. O mecanismo é o mesmo de qualquer assinatura; a diferença é que quem recebe já perguntou. Esse é o argumento desenvolvido em <a href="https://changeloop.dev/blog/pt-br/customer-feedback-loop/">fechar o loop de feedback pelo lado do changelog</a>.</p> <h2>FAQ</h2> <p><strong>A página de changelog deveria estar em um subdomínio ou em um caminho?</strong> Por padrão, um caminho no site principal, porque herda a autoridade do site e não precisa de infraestrutura extra. Um subdomínio se justifica quando um sistema diferente serve a página.</p> <p><strong>Quantas entradas a página deveria mostrar de uma vez?</strong> O suficiente para preencher uma tela e não mais, com paginação depois disso. Carregar dois anos de histórico em um único documento é lento e dificulta encontrar a entrada mais recente.</p> <p><strong>Entradas antigas deveriam algum dia ser apagadas?</strong> Não. Elas são citadas de fora do seu site, e os links quebram. Corrija uma entrada no lugar com uma nota, e mantenha a URL viva.</p> <p><strong>Toda mudança precisa aparecer na página?</strong> Só as que um usuário poderia notar. Uma página que registra refatorações internas treina os leitores a passar os olhos rapidamente, e uma página assim falha no dia em que carrega algo urgente.</p> </article> <article> <h1>O template de e-mail de atualização de produto que é lido</h1> <p>Wed, 02 Sep 2026 00:00:00 GMT</p> <p>O e-mail de atualização de produto que é lido é aquele enviado para alguém que pediu exatamente o que ele anuncia. Tudo o mais compete com o resto da caixa de entrada em interesse, uma disputa que um anúncio de release perde na maioria das semanas. Esse único fato deveria decidir a forma do e-mail antes de qualquer redação: quem o recebe, e o que essa pessoa fez para acabar na lista.</p> <h2>O que é um e-mail de atualização de produto?</h2> <p>É uma mensagem contando aos usuários existentes o que mudou em um produto que eles já usam. Existem quatro tipos distintos, e tratá-los como uma única lista é o motivo pelo qual as taxas de abertura caem. Cada um tem um gatilho diferente, um público diferente e uma frequência aceitável diferente.</p> <table> <thead> <tr> <th>Tipo</th> <th>Gatilho</th> <th>Público</th> <th>Frequência</th> </tr> </thead> <tbody><tr> <td>Notificação direcionada</td> <td>O pedido específico de alguém foi lançado</td> <td>Uma pessoa</td> <td>Sempre que acontece</td> </tr> <tr> <td>Aviso de mudança que quebra algo</td> <td>Uma mudança que custa trabalho ao leitor</td> <td>Só contas afetadas</td> <td>Sempre que acontece</td> </tr> <tr> <td>Digest</td> <td>A passagem do tempo</td> <td>Usuários opt-in</td> <td>No máximo mensal</td> </tr> <tr> <td>Anúncio de lançamento</td> <td>Um lançamento que vale a interrupção</td> <td>Segmento ou todos</td> <td>Raro, e deveria parecer raro</td> </tr> </tbody></table> <p>A maioria dos times constrói só o terceiro tipo, manda para todo mundo, e conclui que e-mails de atualização de produto não funcionam. Os dois primeiros carregam quase todo o valor, porque o leitor já tem um motivo anterior para se interessar, e a mensagem chega enquanto esse motivo ainda está vivo.</p> <p>Essas quatro linhas aqui são todas escritas para clientes. Vendas, suporte e customer success também precisam saber o que foi lançado, geralmente em um formato diferente dessas quatro; <a href="https://changeloop.dev/blog/pt-br/internal-release-notes/">release notes internas</a> cobre o que esse documento deveria dizer e por que precisa sair antes da nota voltada para o cliente.</p> <p>E-mail é um entre vários canais que um anúncio de lançamento pode usar, não o único. <a href="https://changeloop.dev/blog/pt-br/new-feature-announcement/">Como anunciar uma funcionalidade nova</a> cobre os outros, e como escolher entre eles pelo quão grande a funcionalidade realmente é.</p> <h2>O que entra no template?</h2> <p>Seis blocos, nessa ordem. O primeiro é o que costuma faltar, e o que faz o trabalho.</p> <pre><code>Assunto: <o que mudou, com as palavras do leitor> 1. Por que você está recebendo isso "Você pediu exportação em CSV em março." ou "Sua integração chama /v1/invoices, que muda em 15 de janeiro." 2. O que mudou Uma frase. O que agora é possível, ou o que agora quebra. 3. O que você precisa fazer Frequentemente "nada". Diga isso explicitamente, não deixe implícito. 4. Onde ver isso Um link para a entrada do changelog, não para a página inicial. 5. Quando A data em que foi lançado, ou desde quando vale. 6. Como cancelar a inscrição Um clique, respeitado imediatamente. </code></pre> <p>O bloco 1 é a diferença entre uma mensagem e uma transmissão geral. Um leitor a quem se diz, na primeira frase, que essa é a resolução de algo que ele pediu pessoalmente, lê o resto. Sem ele, os blocos 2 a 5 são uma newsletter, por melhor que estejam escritos.</p> <p>Mantenha o todo abaixo de cerca de 150 palavras. O e-mail é um ponteiro para a entrada do changelog, e é lá que o detalhe pertence. Um e-mail que reproduz a entrada inteira não dá ao leitor um motivo para clicar, nem a você um sinal se alguém se importou.</p> <h2>Que assuntos funcionam?</h2> <p>Nomeie a mudança, não o release. "A exportação em CSV está no ar" vence "atualização de setembro" porque o primeiro é um fato que o leitor pode avaliar e o segundo é um contêiner. Números de versão no assunto são úteis para chamadores de uma API e ruído para todos os outros, mais um motivo para separar os públicos.</p> <p>Evite afirmar um benefício com o qual o leitor não concordou. "Seus relatórios agora estão mais rápidos" afirma algo sobre a experiência dele; "Relatórios com mais de 10.000 linhas agora carregam em menos de um segundo" reporta uma mudança e deixa ele decidir se isso importa.</p> <h2>Quando enviar um, e para quem?</h2> <p>Envie uma notificação direcionada no momento em que a coisa é lançada, para as pessoas que pediram, individualmente. Envie um aviso de mudança que quebra algo assim que a data estiver certa e de novo perto dela, para as contas realmente afetadas em vez da lista inteira. Envie um digest só se você tiver mudanças suficientes para que um leitor perdesse algo de outra forma, e deixe as pessoas se inscreverem separadamente.</p> <p>A lista que você quase nunca deveria usar é "todos os usuários". Ela transforma uma mensagem específica em uma genérica, e treina o cancelamento de inscrição. Segmente por comportamento que você já armazena: quem pediu, quem usa esse endpoint, quem está nesse plano.</p> <h2>É preciso consentimento para enviar isso?</h2> <p>Para clientes existentes, uma atualização sobre um serviço que eles usam geralmente é uma questão legal diferente de marketing para um potencial cliente, e a resposta depende de onde eles estão e do que você disse a eles no cadastro. Na UE, a pergunta relevante é qual base legal do <a href="https://gdpr-info.eu/art-6-gdpr/">artigo 6º do GDPR</a> se aplica, e nos Estados Unidos mensagens comerciais carregam exigências específicas estabelecidas no <a href="https://www.ftc.gov/business-guidance/resources/can-spam-act-compliance-guide-business">guia de conformidade CAN-SPAM da FTC</a>. Ambos exigem na prática a mesma coisa: diga quem você é, deixe o propósito claro, e permita que as pessoas possam parar.</p> <p>Seja qual for a base, mantenha os fluxos transacional e de marketing separados no nível de envio. Um aviso de mudança que quebra algo do qual um cliente se desinscreveu porque dividia lista com um digest promocional é um incidente de suporte esperando sua data.</p> <h2>Como fica preenchido?</h2> <p>A notificação direcionada, o e-mail de atualização de produto de maior valor e o que a maioria dos times nunca constrói:</p> <pre><code>Assunto: A exportação em CSV está no ar Oi Dana, você pediu exportação em CSV em março. Foi ao ar hoje de manhã. Os relatórios agora têm um botão Exportar que gera um CSV da visão atual, incluindo filtros. Nada para você fazer. Já está ativado na sua conta. Detalhes: example.com/changelog#csv-export Lançado: 2 de setembro de 2026 Você está recebendo isso porque pediu. Cancelar inscrição em atualizações de pedidos: <link> </code></pre> <p>Noventa palavras, e o leitor sabe na primeira frase por que isso chegou. Compare com a mesma mudança em um digest mensal, onde aparece como um item entre nove e Dana não tem motivo para notar que o próprio pedido dela saiu.</p> <h2>O que você deveria medir?</h2> <p>Não só a taxa de abertura. Para uma notificação direcionada, a pergunta é se a pessoa que pediu voltou e usou a coisa, então o número a observar é o clique para a entrada e se aquela conta usa a funcionalidade em uma semana. Para um aviso de mudança que quebra algo, é a cobertura: que fração das contas afetadas abriu antes da data, e com quem você fez follow-up individual.</p> <p>Um digest é o único dos quatro onde uma taxa de abertura significa muita coisa, e mesmo lá é mais útil como tendência contra o próprio histórico do que contra um benchmark do setor. Tipos diferentes de e-mail de atualização de produto têm tarefas diferentes, então um número médio entre todos não descreve nada em que se possa agir.</p> <h2>Em que isso difere de notas de versão?</h2> <p>Notas de versão são um documento que permanece disponível. O e-mail é um mecanismo de entrega que acontece uma vez. A mesma mudança produz os dois, e o e-mail deveria ser mais curto do que a entrada para a qual aponta. <a href="https://changeloop.dev/blog/pt-br/release-notes-best-practices/">Boas práticas de notas de versão</a> cobre o documento, e <a href="https://changeloop.dev/blog/pt-br/changelog-vs-release-notes/">changelog vs notas de versão</a> cobre qual dos dois você está escrevendo.</p> <p>A relação que vale a pena acertar: a entrada do changelog é o texto canônico e o e-mail a cita. Quando os dois divergem, o leitor que clica encontra uma descrição diferente da mudança e para de confiar nos dois. Publicar a entrada primeiro e gerar o e-mail a partir dela elimina a divergência por construção. O changeloop funciona do mesmo jeito do lado dele: uma entrada é revisada uma vez e publicada na <a href="https://changeloop.dev/docs">página, no feed e no widget</a>, e a pessoa que a pediu pelo widget é avisada na issue do GitHub em que o feedback dela se transformou, e no próprio widget. O changeloop não envia o e-mail; a sua ferramenta de e-mail cita a entrada publicada.</p> <h2>FAQ</h2> <p><strong>Com que frequência um e-mail de atualização de produto deveria sair?</strong> Tão frequentemente quanto houver algo específico que o destinatário queira saber, o que para uma notificação direcionada significa sempre que o pedido dele é lançado, e para um digest significa no máximo mensal.</p> <p><strong>O e-mail deveria conter a entrada inteira do changelog?</strong> Não. Uma frase e um link. A entrada é a versão canônica, e uma cópia completa no e-mail significa dois textos para manter alinhados.</p> <p><strong>Que taxa de abertura eu deveria esperar?</strong> Compare cada tipo com ele mesmo, não com um benchmark. Uma notificação direcionada e um digest mensal são produtos diferentes, e tirar a média deles esconde o único número que vale a pena observar.</p> <p><strong>Preciso de uma lista separada para mudanças que quebram algo?</strong> Sim, e deveria ser aquela da qual as pessoas não podem se desinscrever casualmente sem entender a consequência, porque é a que custa uma interrupção a elas.</p> </article> <article> <h1>Como depreciar uma API sem perder seus desenvolvedores</h1> <p>Sat, 29 Aug 2026 00:00:00 GMT</p> <p>Depreciar uma API é anunciar que algo ainda funciona hoje e vai parar de funcionar em uma data declarada, e então cumprir as duas metades dessa promessa. A maioria das depreciações falha na segunda metade: a data escorrega silenciosamente, ou chega e os chamadores que nunca viram o aviso descobrem por um erro. Uma depreciação está terminada quando todo chamador afetado migrou ou recebeu, individualmente, a informação de que não migrou.</p> <h2>O que é depreciação de API?</h2> <p>Depreciação é o período entre anunciar que um endpoint, campo ou versão vai sumir e realmente removê-lo. Durante esse período o comportamento antigo continua funcionando, a documentação diz que está saindo, e toda resposta carrega um aviso legível por máquina. Remoção é o evento separado, posterior, muitas vezes chamado de sunset. Os dois se confundem, e essa confusão é onde o dano acontece: "deprecated" começa a significar "pode já ter sumido", e os chamadores param de confiar em nenhuma das duas palavras.</p> <table> <thead> <tr> <th>Termo</th> <th>Significado</th> <th>No que os chamadores podem confiar</th> </tr> </thead> <tbody><tr> <td>Deprecated</td> <td>Anunciado como saindo, ainda funciona</td> <td>Comportamento completo até a data de sunset</td> </tr> <tr> <td>Sunset</td> <td>A data em que para de funcionar</td> <td>Nada depois dessa data</td> </tr> <tr> <td>Retired / removido</td> <td>Sumiu; requisições falham</td> <td>Um erro, idealmente um que nomeie o substituto</td> </tr> <tr> <td>Legacy</td> <td>Indefinido. Evite a palavra</td> <td>Nada, que é o problema</td> </tr> </tbody></table> <h2>Quanto tempo deveria durar um período de depreciação?</h2> <p>O suficiente para um chamador descobrir e fazer o trabalho, medido a partir de quando o aviso o alcançou, não a partir de quando vocês o escreveram. Noventa dias é o piso comum para uma API web pública. Doze meses é normal para qualquer coisa embutida em software que usuários finais instalam, porque a correção também precisa passar pelo processo de release deles. A orientação de versionamento do Google, a <a href="https://google.aip.dev/185">AIP-185</a>, pede um período de transição razoável e recomenda 180 dias mesmo antes de remover funcionalidades beta, e o Kubernetes documenta sua <a href="https://kubernetes.io/docs/reference/using-api/deprecation-policy/">política de depreciação</a> em contagem de releases em vez de meses, o que é a unidade certa quando os chamadores de vocês atualizam por versão.</p> <p>Escolham um período, escrevam-no como política, e parem de decidi-lo por mudança. Uma política publicada transforma cada depreciação de uma negociação em uma aplicação de regra.</p> <p>Escrever a política de depreciação cobre o início da janela; <a href="https://changeloop.dev/blog/pt-br/sunsetting-api-version/">descontinuando uma versão de API</a> cobre o aviso separado necessário no final, quando o período realmente acaba e a versão para de funcionar.</p> <h2>O cronograma de depreciação</h2> <p>Quatro datas, anunciadas juntas no primeiro dia. Cada uma é uma entrada de changelog separada quando chega, então a história é contada quatro vezes a quem só lê o changelog.</p> <ol> <li><strong>Anunciar.</strong> A entrada diz o que está sendo depreciado, por quê, o que o substitui, e a data de sunset. A documentação da coisa antiga ganha um banner que linka para a migração. As respostas ganham os headers descritos abaixo.</li> <li><strong>Lembrar, na metade do caminho.</strong> Uma segunda entrada, e uma mensagem direta a todo chamador ainda usando o comportamento antigo. Este é o passo que precisa de dados de uso: se vocês não conseguem listar quem ainda está chamando o endpoint depreciado, vocês não conseguem fazer isso, e vale a pena corrigir antes da próxima depreciação.</li> <li><strong>Brownout, pouco antes da data.</strong> Retorne erros para o comportamento antigo por uma janela curta, uma hora ou um dia, depois restaure. Chamadores que perderam todo aviso descobrem agora, enquanto ainda há tempo. O GitHub usou brownouts programados antes de <a href="https://github.blog/2020-07-30-token-authentication-requirements-for-api-and-git-operations/">aposentar a autenticação por senha para a API</a>, e é o passo individual mais eficaz desta lista.</li> <li><strong>Sunset.</strong> Remova. O erro que o substitui nomeia o substituto e linka o guia de migração. Mantenha o erro no lugar por muito tempo; um 404 não diz nada a um chamador.</li> </ol> <h2>O que um aviso de depreciação deveria dizer?</h2> <p>Um aviso de depreciação diz o que está saindo, quando para, o que usar em vez disso, e quem é afetado. Aqui está a forma, preenchida:</p> <blockquote> <p><strong><code>GET /v1/reports/daily</code> está depreciado e para de funcionar em 1º de março de 2027.</strong> É substituído por <code>GET /v2/reports?granularity=day</code>, que retorna os mesmos dados com um esquema estável e paginação. Afeta as 214 integrações que chamaram o endpoint v1 nos últimos 30 dias; se a sua for uma delas, você também receberá este aviso por e-mail. Guia de migração: [link]. Nada muda até 1º de março de 2027. A partir dessa data o endpoint v1 retorna <code>410 Gone</code> com um link para esta entrada.</p> </blockquote> <p>Toda frase carrega algo de que a leitora precisa. A contagem de integrações afetadas diz a cada leitora se ela deve continuar lendo. "Nada muda até" é a frase que permite que quem não é afetado feche a aba. A página <a href="https://changeloop.dev/changelog-examples">exemplos de changelog</a> reúne entradas de equipes que escrevem essa forma consistentemente, e vale a pena ler três antes de escrever a primeira própria.</p> <h2>Quais headers um endpoint depreciado deveria enviar?</h2> <p>Envie <code>Deprecation</code>, <code>Sunset</code> e um <code>Link</code> para o sucessor, em toda resposta do endpoint depreciado, a partir do dia do anúncio. O <a href="https://datatracker.ietf.org/doc/html/rfc9745">header <code>Deprecation</code></a> carrega a data em que a depreciação entrou em vigor; o <a href="https://datatracker.ietf.org/doc/html/rfc8594">header <code>Sunset</code></a> carrega a data em que o endpoint para de responder; <code>Link: <url>; rel="successor-version"</code> aponta para o que usar em vez disso.</p> <pre><code>HTTP/1.1 200 OK Deprecation: @1756425600 Sunset: Mon, 01 Mar 2027 00:00:00 GMT Link: <https://api.example.com/v2/reports>; rel="successor-version" Link: <https://example.com/changelog/daily-reports>; rel="deprecation" </code></pre> <p>A maioria dos chamadores nunca vai ler os headers pessoalmente. O valor deles está em que o cliente HTTP, o gateway ou o monitoramento de um chamador pode, o que transforma a depreciação de vocês em um alerta do lado deles em vez de uma página do lado de vocês. SDKs que vocês enviam deveriam registrar um aviso quando virem um.</p> <h2>Quem foi informado, e como vocês sabem?</h2> <p>Este é o passo que decide se o sunset é tranquilo ou um incidente de suporte, e é o mais difícil de fazer só com um changelog. Uma entrada de changelog informa todo mundo que lê o changelog. Uma depreciação precisa alcançar as pessoas específicas cujo código vai falhar, e a forma usual de encontrá-las é os mesmos dados de uso de que precisa o lembrete na metade do caminho: as chaves de API, apps ou contas que chamaram o comportamento depreciado recentemente.</p> <p>O ciclo que rodamos: a entrada é redigida a partir do pull request que adiciona a depreciação, uma pessoa revisa a formulação e a data, e uma vez publicada a entrada em si é a notificação. Quem mandou pelo widget um feedback sobre o problema, ou um pedido pelo substituto, que virou uma issue do GitHub fechada pelo pull request, recebe um comentário nessa issue dizendo que foi lançado, com um link para a entrada. <a href="https://changeloop.dev/docs">Feed e widget</a> servem a mesma entrada a todos os outros, junto com cada outra entrada no <a href="https://changeloop.dev/blog/pt-br/api-changelog/">changelog de API</a>. O que não fazemos é deixar a depreciação virar "lançada" antes de uma pessoa tê-la publicado; um aviso com a data errada é pior que nenhum aviso.</p> <p>Seja qual for a ferramenta de vocês, a pergunta que você deve conseguir responder no dia do sunset é: quais chamadores ainda estavam usando isso na semana passada, e quais deles avisamos diretamente? Se a resposta for "publicamos algo sobre isso", o sunset não está pronto.</p> <h2>Qual é a diferença entre depreciar e versionar?</h2> <p>Versionar é como você mantém o comportamento antigo disponível enquanto o novo existe; depreciação é como você aposenta o antigo. Uma nova versão de API sem uma política de depreciação para a anterior é um compromisso de rodar as duas para sempre. Uma depreciação sem versionamento é uma <a href="https://changeloop.dev/blog/pt-br/breaking-changes/">mudança que quebra algo</a> com atraso. Vocês precisam de ambos, e a versão é a metade mais fácil. O GraphQL é a exceção que vale a pena nomear: geralmente não existe nenhum número de versão para incrementar, e <a href="https://changeloop.dev/blog/pt-br/graphql-schema-deprecation/">depreciação de schema no GraphQL</a> cobre como um único schema compartilhado aposenta um campo com uma diretiva em vez disso.</p> <h2>FAQ</h2> <p><strong>Um endpoint depreciado deveria continuar funcionando exatamente como antes?</strong> Sim, até a data de sunset. As únicas mudanças permitidas são os headers adicionados e, perto do fim, um brownout programado que vocês anunciaram com antecedência.</p> <p><strong>Qual código de status um endpoint aposentado deveria retornar?</strong> <code>410 Gone</code>, com um corpo e um header <code>Link</code> apontando para o substituto e a entrada de changelog. <code>404</code> diz que a URL nunca existiu, o que é falso e inútil.</p> <p><strong>Um período de depreciação pode ser encurtado?</strong> Só por segurança. Se o comportamento antigo é explorável, digam isso, encurtem o período, e avisem todo chamador afetado diretamente em vez de confiar no changelog.</p> <p><strong>Preciso depreciar um campo, ou só endpoints inteiros?</strong> Campos, parâmetros, valores de enum, padrões e headers todos precisam do mesmo tratamento, porque cada um pode quebrar um chamador correto. Um campo removido é a depreciação mais comum e a mais frequentemente ignorada.</p> </article> <article> <h1>Melhores práticas de versionamento de API, para chamadores</h1> <p>Sat, 29 Aug 2026 00:00:00 GMT</p> <p>Versionamento de API é a prática de manter um contrato antigo funcionando depois que vocês o mudaram, para que chamadores possam avançar no cronograma deles em vez do de vocês. Essa frase contém as duas decisões que importam: o que conta como mudar o contrato, e por quanto tempo o antigo continua funcionando. Onde o número de versão vive, sobre o que trata a maioria dos debates de versionamento, é a menos importante das três e a mais fácil de acertar.</p> <h2>Quando uma API deveria ser versionada?</h2> <p>Versione uma API só quando uma mudança quebraria um chamador correto. Mudanças aditivas, novos campos, novos endpoints, novos parâmetros opcionais, não precisam de uma versão; chamadores escritos contra o contrato antigo continuam funcionando e a nova capacidade simplesmente está lá. Uma <a href="https://changeloop.dev/blog/pt-br/breaking-changes/">mudança que quebra algo</a> precisa de uma, porque a alternativa é um chamador descobrir por um erro. Versionar toda release, incluindo as aditivas, ensina chamadores que versões são ruído, e eles param de ler os avisos que importam.</p> <p>O teste prático é o mesmo do artigo sobre mudanças que quebram algo: se um chamador que dependia apenas de comportamento documentado precisa mudar algo para continuar funcionando, a mudança precisa de uma versão. Se não, lance sob a versão atual e escreva uma entrada de changelog.</p> <h2>Qual esquema de versionamento de API deveria ser usado?</h2> <p>Use o esquema que seus chamadores conseguem ver e fixar mais facilmente, o que para a maioria das APIs públicas é uma versão no caminho da URL ou um header de versão datado. Os quatro esquemas comuns diferem menos em capacidade do que no que pedem do chamador, e essa é a base certa para escolher.</p> <table> <thead> <tr> <th>Esquema</th> <th>Exemplo</th> <th>O que o chamador deve fazer</th> <th>Quem usa</th> </tr> </thead> <tbody><tr> <td>Caminho de URL</td> <td><code>/v2/invoices</code></td> <td>Mudar a URL ao migrar</td> <td>A maioria das APIs REST públicas</td> </tr> <tr> <td>Header de versão</td> <td><code>X-GitHub-Api-Version: 2022-11-28</code></td> <td>Enviar um header, ou aceitar o padrão</td> <td>GitHub</td> </tr> <tr> <td>Versão de conta datada</td> <td><code>Stripe-Version: 2026-08-26</code></td> <td>Fixar uma data por requisição ou por conta</td> <td>Stripe</td> </tr> <tr> <td>Parâmetro de query</td> <td><code>/invoices?version=2</code></td> <td>Adicionar um parâmetro</td> <td>APIs mais antigas; raramente escolhido agora</td> </tr> <tr> <td>Media type</td> <td><code>Accept: application/vnd.example.v2+json</code></td> <td>Negociar tipos de conteúdo</td> <td>Puristas; poucos chamadores dominam</td> </tr> </tbody></table> <p><strong>Caminho de URL</strong> é o mais visível e o menos flexível. Todo chamador consegue ver em qual versão está lendo uma linha de log, e um salto de versão é um buscar-e-substituir. O custo: toda a superfície se move de uma vez, vocês não conseguem mudar o contrato de um único endpoint sem cunhar uma nova versão para todos, então versões de caminho tendem a ser raras e grandes.</p> <p><strong>Header de versão</strong> mantém as URLs estáveis e deixa o servidor escolher um padrão para chamadores que não enviam nada, como funciona o <a href="https://docs.github.com/en/rest/about-the-rest-api/api-versions">versionamento da API REST do GitHub</a>: uma versão nomeada por data em <code>X-GitHub-Api-Version</code>, com a versão suportada mais antiga como padrão para que chamadores sem versão não quebrem. O custo: a versão é invisível em uma URL e fácil de esquecer em um cliente novo.</p> <p><strong>Versão de conta datada</strong> é o esquema de header mais uma adição: a versão é armazenada contra a conta, então toda requisição a recebe sem enviar nada. O <a href="https://docs.stripe.com/api/versioning">versionamento de API do Stripe</a> fixa cada conta na versão com que foi criada e deixa uma requisição sobrescrever isso com <code>Stripe-Version</code>. Esse é o esquema mais amigável ao chamador e o que dá mais trabalho para operar, porque o servidor precisa traduzir entre cada versão suportada e a atual.</p> <p><strong>Parâmetro de query</strong> e <strong>media type</strong> ambos funcionam e ambos falham no teste de visibilidade de formas diferentes: um parâmetro de query cai facilmente ao construir uma URL, e uma versão de media type é invisível para quase qualquer ferramenta com a qual um chamador debugaria. O esquema por data do Stripe é o exemplo mais conhecido da abordagem por data, e <a href="https://changeloop.dev/blog/pt-br/stripe-api-versioning/">como o Stripe versiona sua API</a> o detalha.</p> <h2>Como se faz versionamento de API na prática?</h2> <p>Na prática uma versão é um conjunto nomeado de comportamentos, e o servidor mapeia cada requisição para um deles. Os passos são os mesmos independentemente de qual esquema carrega o nome.</p> <ol> <li><strong>Nomeie versões por data ou por número inteiro, não por versão semântica.</strong> Uma API web não é um pacote. Chamadores não conseguem fixar uma versão minor de uma URL, então <code>v2</code> ou <code>2026-08-26</code> diz tudo que um chamador precisa, e o <a href="https://semver.org/">versionamento semântico</a> implica uma promessa de compatibilidade que o esquema não consegue cumprir.</li> <li><strong>Mantenha a versão fora dos caminhos de código que não se importam com ela.</strong> Uma versão deveria selecionar uma camada de tradução na borda, não bifurcar a lógica de negócio. Duas cópias completas da base de código é como uma versão acaba sem manutenção.</li> <li><strong>Dê a cada versão um padrão e um documento.</strong> Chamadores que não enviam versão recebem a mais antiga suportada, nunca a mais nova, para que um cliente não fixado não quebre no dia do lançamento. Cada versão tem uma página dizendo o que mudou em relação à anterior.</li> <li><strong>Defina uma janela de suporte e publique-a.</strong> A orientação de versionamento do Google, a <a href="https://google.aip.dev/185">AIP-185</a>, pede um período de transição razoável e bem comunicado e recomenda 180 dias mesmo para funcionalidades beta. Escolham uma janela, escrevam-na, e apliquem sem renegociar por versão.</li> <li><strong>Aposentem versões da mesma forma que aposentam endpoints.</strong> Uma versão que passou de sua janela recebe o mesmo tratamento que qualquer <a href="https://changeloop.dev/blog/pt-br/api-deprecation/">API depreciada</a>: um anúncio, um header <code>Sunset</code> (<a href="https://datatracker.ietf.org/doc/html/rfc8594">RFC 8594</a>) em toda resposta, um lembrete na metade do caminho aos chamadores restantes, e uma data de remoção que se mantém.</li> </ol> <h2>O que são v1 e v2 em uma API REST?</h2> <p><code>v1</code> e <code>v2</code> são nomes para dois contratos que o mesmo servidor suporta ao mesmo tempo. Um <code>v2</code> existe porque algo em <code>v1</code> não podia ser mudado sem quebrar seus chamadores, então a mudança foi para um novo contrato e o antigo continuou funcionando. Os números não implicam que <code>v2</code> está completo ou que <code>v1</code> está morto; ambos só são verdade se a documentação disser. Um <code>v3</code> que aparece a cada trimestre é um sinal de que mudanças aditivas estão sendo versionadas, ou que o contrato nunca foi desenhado para absorver mudança.</p> <p>Esse é o modelo de versionamento por caminho de URL, onde o número de versão é o segmento que a chamadora disca. Serviços gRPC geralmente resolvem o mesmo problema de outra forma: a versão mora no nome do pacote dentro do próprio arquivo <code>.proto</code>. <a href="https://changeloop.dev/blog/pt-br/grpc-protobuf-api-changes/">gRPC e Protobuf</a> cobre essa diferença e por que lá a compatibilidade no fio é definida por números de campo, não pela forma da URL.</p> <h2>O que uma mudança de versão deveria anunciar?</h2> <p>Uma mudança de versão deveria anunciar o que quebra, quem é afetado, como migrar, e por quanto tempo a versão anterior continua funcionando. A entrada tem a mesma forma de qualquer outra entrada de mudança que quebra algo, mais uma linha declarando a janela de suporte. Aqui está uma para uma API versionada por header:</p> <blockquote> <p><strong>A versão de API 2026-11-01 está disponível. A versão 2025-06-15 é suportada até 1º de novembro de 2027.</strong> Novidade em 2026-11-01: <code>GET /invoices</code> retorna <code>amount</code> em unidades mínimas como um número inteiro em vez de string decimal, e o campo depreciado <code>customer_name</code> é removido em favor do objeto <code>customer</code>. Afeta chamadores em 2025-06-15 que parseiam <code>amount</code> como string, que é o padrão para clientes não fixados criados antes de junho de 2025. Migração: parseie <code>amount</code> como inteiro e leia o nome de <code>customer.name</code>. Fixe <code>X-Api-Version: 2026-11-01</code> quando estiver pronto. Nada muda para chamadores que não fixam versão.</p> </blockquote> <p>A última frase é a que permite que a maioria das leitoras pare de ler, e pertence a todo anúncio de versão. A página <a href="https://changeloop.dev/changelog-examples">exemplos de changelog</a> inclui entradas de APIs que versionam assim, e a diferença entre as boas e o resto está principalmente nessa última frase.</p> <h2>Quem é informado quando uma versão muda?</h2> <p>Todo mundo na versão antiga, individualmente, e o changelog para todos os outros. Uma mudança de versão é o único caso em que "publicamos algo sobre isso" garantidamente perde exatamente os chamadores que importam: os que fixaram uma versão dois anos atrás e não leem uma nota de release desde então. Dados de uso respondem quem eles são; o aviso precisa alcançá-los onde está o código deles, nos headers de resposta e em uma mensagem para a dona da conta.</p> <p>No ciclo que rodamos, a entrada que anuncia uma versão é redigida a partir do pull request que a lança, revisada por uma pessoa, e publicada em <a href="https://changeloop.dev/docs">feed e widget</a>, onde um cliente versionado pode lê-la como JSON. Quem pediu a mudança, ou relatou o bug que ela resolve, por um feedback no widget que virou uma issue do GitHub fechada pelo pull request, é informado nessa issue assim que a entrada entra no ar. O mecanismo é o mesmo de qualquer entrada; um salto de versão é só a entrada com a aposta mais alta.</p> <h2>FAQ</h2> <p><strong>Toda mudança de API deveria receber uma nova versão?</strong> Não. Só as mudanças que quebram algo. Mudanças aditivas são lançadas sob a versão atual com uma entrada de changelog. Versionar mudanças aditivas treina chamadores a ignorar versões.</p> <p><strong>Versionamento por URL é melhor que por header?</strong> Versionamento por URL é mais fácil de ver para chamadores e mais difícil de evoluir aos poucos para vocês; versionamento por header é o contrário. Para uma API pública com muitos clientes pequenos, versionamento por URL falha menos. Para uma API grande com camada de tradução, a versão datada por header escala melhor.</p> <p><strong>Quantas versões deveriam ser suportadas ao mesmo tempo?</strong> As menos possíveis que sua janela de suporte permita, e nunca um número ilimitado. Duas ou três versões concorrentes é normal; mais que isso geralmente significa que versões não estão sendo aposentadas.</p> <p><strong>O que requisições sem versão deveriam receber?</strong> A versão suportada mais antiga, para que clientes existentes não fixados continuem funcionando, com um header de resposta dizendo qual versão eles receberam.</p> </article> <article> <h1>Mudanças que quebram algo: o que conta e como lançá-las</h1> <p>Sat, 29 Aug 2026 00:00:00 GMT</p> <p>Uma mudança que quebra algo é uma mudança que um chamador escrito corretamente não conseguiria sobreviver. A definição importa porque a maioria dos debates sobre se algo "conta" na verdade são debates sobre quem estava segurando errado. Se um chamador seguiu a documentação de vocês e a mudança de vocês fez o código dele parar de funcionar, a mudança quebrava algo. O que vocês pretendiam não tem nada a ver com isso.</p> <p>Esse é todo o teste. O resto deste artigo é o que decorre disso: o que falha no teste, o que passa, como pegar uma falha antes que ela seja mergeada, e o que fazer assim que você sabe que está lançando uma.</p> <h2>O que conta como uma mudança que quebra algo?</h2> <p>Aplique o teste ao chamador, não ao diff. Uma mudança quebra algo quando um chamador que dependia apenas de comportamento documentado precisa mudar seu código, sua configuração ou seus dados para continuar funcionando. Remover um campo, renomear um endpoint, apertar a validação, mudar um padrão e mudar o tipo de um valor se qualificam todos. Adicionar um campo opcional não se qualifica. Corrigir um bug geralmente não se qualifica, com uma exceção importante abaixo.</p> <table> <thead> <tr> <th>Mudança</th> <th>Quebra algo?</th> <th>Por quê</th> </tr> </thead> <tbody><tr> <td>Remover ou renomear um campo, endpoint, flag ou opção</td> <td>Sim</td> <td>Chamadores corretos referenciam isso</td> </tr> <tr> <td>Adicionar um campo opcional ou um novo endpoint</td> <td>Não</td> <td>Chamadas existentes não mudam</td> </tr> <tr> <td>Tornar uma entrada opcional obrigatória</td> <td>Sim</td> <td>Chamadas que omitiam falham agora</td> </tr> <tr> <td>Apertar validação previamente aceita</td> <td>Sim</td> <td>Entradas que funcionavam agora são rejeitadas</td> </tr> <tr> <td>Mudar um valor padrão</td> <td>Sim</td> <td>Chamadores que não o definiram recebem comportamento novo</td> </tr> <tr> <td>Mudar um tipo (string para número, valor único para array)</td> <td>Sim</td> <td>Parsers escritos para o tipo documentado falham</td> </tr> <tr> <td>Reordenar as chaves de um objeto</td> <td>Não</td> <td>A menos que vocês tenham documentado a ordem</td> </tr> <tr> <td>Corrigir um bug do qual chamadores dependiam</td> <td>Na prática, sim</td> <td>Ver a seção sobre contratos acidentais</td> </tr> <tr> <td>Elevar um limite de taxa ou um teto de tamanho</td> <td>Não</td> <td>Nada que funcionava para de funcionar</td> </tr> <tr> <td>Reduzir um limite de taxa ou um teto de tamanho</td> <td>Sim</td> <td>Tráfego que estava bem agora é limitado</td> </tr> <tr> <td>Mudar a formulação de uma mensagem de erro</td> <td>Depende</td> <td>Quebra algo se vocês documentaram ou chamadores dão match nisso</td> </tr> </tbody></table> <h2>O que não é uma mudança que quebra algo?</h2> <p>Uma mudança não quebra nada quando toda chamada que funcionava antes continua funcionando, sem alteração, e continua significando a mesma coisa. Adicionar um novo endpoint, adicionar um parâmetro opcional de requisição, adicionar um campo a uma resposta, tornar uma entrada obrigatória opcional, elevar um limite e melhorar uma mensagem de erro em que ninguém dá match passam todos no teste. Essas mudanças aditivas podem sair em uma release minor com uma entrada de changelog comum.</p> <p>Mudanças aditivas ainda quebram chamadores em três situações. Um cliente cujo deserializador rejeita campos desconhecidos falha no primeiro campo novo da resposta, então documente cedo que os chamadores devem ignorar campos que não reconhecem. Um novo valor de enum quebra todo chamador com um switch exaustivo (mais sobre isso abaixo). E uma resposta que cresce pode empurrar um chamador além de um limite de tamanho, de um timeout ou de uma largura de coluna em que ele nunca precisou pensar.</p> <p>Quatro linhas da tabela merecem um olhar mais atento, porque é onde as discordâncias acontecem.</p> <h2>As quatro mudanças que quebram algo que as equipes ignoram</h2> <p><strong>Contratos acidentais.</strong> Se a API de vocês retornou o mesmo campo não documentado por três anos, um chamador construiu em cima disso. A <a href="https://www.hyrumslaw.com/">Lei de Hyrum</a> é a versão curta: com usuários suficientes, todo comportamento observável do sistema de vocês terá alguém dependendo dele. É por isso que "foi uma correção de bug" não é uma defesa. A correção pode estar correta e ainda assim quebrar algo. Lancem-na como tal.</p> <p><strong>Mudanças de comportamento sem mudança de esquema.</strong> O campo ainda está lá, o tipo é o mesmo, e o valor agora significa algo diferente. Um <code>status</code> que costumava ser <code>active</code> ou <code>inactive</code> e agora também retorna <code>suspended</code> quebra todo chamador com um switch exaustivo. Um timestamp que muda de hora local para UTC quebra todo mundo que não leu a documentação duas vezes. Nada em um diff do arquivo OpenAPI mostra isso.</p> <p><strong>Validação apertada.</strong> Vocês começam a rejeitar e-mails sem TLD, ou espaços em branco no final, ou nomes com mais de 80 caracteres. Todo chamador que estava enviando exatamente isso agora recebe um 400 para uma requisição que funcionava na semana passada. Mudanças de validação são as mais comumente lançadas como uma correção de "endurecimento".</p> <p><strong>Padrões alterados.</strong> Ninguém que definiu o valor explicitamente percebe nada. Todos que não definiram, que são a maioria dos chamadores, recebem comportamento novo sem mudar uma linha. Um padrão alterado quebra a maioria dos usuários de vocês exatamente porque eles nunca viram a configuração.</p> <h2>Como detectar uma mudança que quebra algo antes que ela seja lançada?</h2> <p>Compare o contrato do pull request com o contrato da branch principal, no CI, e faça o build falhar diante de uma diferença que quebra algo. Existem ferramentas de diff de esquema para a maioria dos formatos de interface, e cada uma conhece as regras de quebra do seu próprio formato:</p> <table> <thead> <tr> <th>Interface</th> <th>Ferramenta</th> <th>O que compara</th> </tr> </thead> <tbody><tr> <td>REST (OpenAPI)</td> <td><a href="https://github.com/oasdiff/oasdiff">oasdiff</a></td> <td>Duas specs OpenAPI, com um relatório de mudanças que quebram algo</td> </tr> <tr> <td>gRPC (Protobuf)</td> <td><a href="https://buf.build/docs/breaking/">buf breaking</a></td> <td>Arquivos <code>.proto</code>, no nível de wire ou de código-fonte</td> </tr> <tr> <td>GraphQL</td> <td><a href="https://github.com/kamilkisiela/graphql-inspector">GraphQL Inspector</a></td> <td>Dois esquemas, sinalizando mudanças que quebram algo e mudanças perigosas</td> </tr> <tr> <td>Crates Rust</td> <td><a href="https://github.com/obi1kenobi/cargo-semver-checks">cargo-semver-checks</a></td> <td>A API pública contra a última versão publicada</td> </tr> <tr> <td>Pacotes TypeScript</td> <td><a href="https://api-extractor.com/">API Extractor</a></td> <td>Um relatório versionado da API pública do pacote</td> </tr> </tbody></table> <p>Essas ferramentas pegam com confiabilidade campos removidos, operações renomeadas e tipos alterados. Elas não enxergam os dois primeiros dos quatro tipos acima, um contrato acidental ou uma mudança de comportamento, porque nenhum dos dois aparece em um esquema. Use a ferramenta para barrar as óbvias e a pergunta de revisão "um chamador correto poderia notar isso?" para o resto. O mesmo job de CI é um lugar natural para exigir uma entrada de changelog, como descrito em <a href="https://changeloop.dev/blog/pt-br/changelog-ci-enforcement/">exigir entradas de changelog no CI</a>, e <a href="https://changeloop.dev/blog/pt-br/grpc-protobuf-api-changes/">mudanças de API em gRPC e Protobuf</a> percorre os casos no nível de wire.</p> <h2>Como marcar uma mudança que quebra algo em um commit?</h2> <p>Com <a href="https://www.conventionalcommits.org/en/v1.0.0/">Conventional Commits</a>, uma mudança que quebra algo é marcada por um <code>!</code> antes dos dois-pontos (<code>feat(api)!: remove the legacy export endpoint</code>) ou por um rodapé que começa com <code>BREAKING CHANGE:</code> seguido de uma descrição. Qualquer um dos dois corresponde a uma versão major. Escreva o rodapé como o primeiro rascunho da entrada de changelog, dizendo quem é afetado e o que deve fazer. <a href="https://changeloop.dev/blog/pt-br/conventional-commits-changelog/">Conventional commits e o changelog</a> mostra até onde a convenção leva vocês.</p> <p>A mesma regra vale para bibliotecas. Uma função pública removida, um tipo de parâmetro estreitado ou um valor de retorno alterado é uma versão major sob versionamento semântico. As bibliotecas nem sempre a seguem: um <a href="https://arxiv.org/abs/2110.07889">estudo de 119.879 atualizações do Maven Central</a> descobriu que 16,6% quebraram o versionamento semântico, mas apenas 7,9% dos projetos clientes foram afetados, porque a maioria dessas mudanças tocava código que nenhum cliente chamava. A quebra se mede no chamador.</p> <h2>Como se lança uma mudança que quebra algo?</h2> <p>Você a lança abertamente, com uma data, com um caminho. Os passos abaixo estão em ordem, e o último é o que a maioria das equipes pula: dizer às pessoas que foram afetadas que o que estavam esperando aconteceu agora.</p> <ol> <li><strong>Decida se é uma.</strong> Use o teste acima, não o diff. Se dois engenheiros discordam, quebra algo; a discordância é evidência de que um chamador poderia razoavelmente ter dependido do comportamento antigo.</li> <li><strong>Versione.</strong> Sob <a href="https://semver.org/">versionamento semântico</a> uma mudança que quebra algo é uma versão major. Se vocês operam uma API datada ou versionada, ela vai para uma nova versão e a antiga continua funcionando até uma data declarada. Se vocês não podem versionar, não estão lançando uma mudança que quebra algo, estão lançando uma interrupção com uma entrada de changelog. Qual esquema carrega a versão é o assunto de <a href="https://changeloop.dev/blog/pt-br/api-versioning-best-practices/">melhores práticas de versionamento de API</a>.</li> <li><strong>Escreva a entrada antes que o código seja mergeado.</strong> A entrada tem uma forma fixa: o que muda, quem é afetado, o que devem fazer, e até quando. Se vocês não conseguem preencher os quatro, a mudança não está pronta. O <a href="https://changeloop.dev/release-notes-template">template de release notes</a> coloca essas entradas primeiro, com uma data em vez de um número de versão, exatamente por isso.</li> <li><strong>Dê um prazo, não um número de release.</strong> "Removido na v5" não significa nada para quem não acompanha as releases de vocês. "Deixa de funcionar em 1º de novembro de 2026" significa a mesma coisa para todos.</li> <li><strong>Forneça a migração.</strong> A chamada antiga ao lado da nova. Se a mudança é uma renomeação, diga os dois nomes na mesma frase; se é um campo removido, diga para onde os dados foram.</li> <li><strong>Anuncie em todo lugar onde o comportamento antigo estava documentado.</strong> O changelog, a página de docs do endpoint, as release notes do SDK e o header de depreciação na resposta, se vocês tiverem um.</li> <li><strong>Feche o ciclo.</strong> Se uma cliente pediu a mudança, ou relatou o bug que levou a ela, diga a ela quando for lançada.</li> </ol> <h2>Como se parece uma boa entrada de mudança que quebra algo?</h2> <p>Uma boa entrada nomeia o chamador afetado na primeira linha, declara a data, e inclui a correção. Aqui está uma para o caso de validação apertada, na forma que usamos:</p> <blockquote> <p><strong>Endereços de e-mail sem domínio são rejeitados a partir de 1º de novembro de 2026.</strong> <code>POST /users</code> e <code>PATCH /users/:id</code> atualmente aceitam valores de <code>email</code> como <code>alice@localhost</code>. A partir de 1º de novembro, esses retornam <code>400 invalid_email</code>. Afeta qualquer integração que cria usuários a partir de diretórios internos. Migração: envie um endereço totalmente qualificado, ou omita o campo e defina-o depois. Nenhuma mudança é necessária se os endereços de vocês já têm um domínio, o que é verdade para 99,4% das contas criadas este ano.</p> </blockquote> <p>Onde esse aviso deve viver, e o que mais deveria acompanhá-lo, é o tema de <a href="https://changeloop.dev/blog/pt-br/api-changelog/">changelog de API</a>.</p> <p>A porcentagem no final não é decoração. Ela diz à leitora se ela deve se preocupar, que é a pergunta com a qual ela abriu a entrada.</p> <h2>Por que não simplesmente evitá-las?</h2> <p>Porque a alternativa é pior. Uma API que nunca quebra nada acumula todo erro que já cometeu: o campo mal nomeado, o padrão errado, o timestamp em hora local. Cada um é um imposto sobre todo novo chamador para sempre, para proteger chamadores que poderiam ter migrado em uma tarde. As equipes com a melhor reputação de estabilidade quebram coisas raramente, em um cronograma, com um caminho de migração e um aviso que alcançou as pessoas para quem era destinado.</p> <p>A mecânica desse aviso é o assunto do artigo complementar sobre <a href="https://changeloop.dev/blog/pt-br/api-deprecation/">depreciar uma API</a>. A entrada que a anuncia é redigida da mesma forma que qualquer outra entrada no <a href="https://changeloop.dev/docs">feed de changelog</a>: a partir do pull request mergeado, retida para um humano, depois publicada no lugar onde os chamadores afetados já leem.</p> <h2>FAQ</h2> <p><strong>Qual é a diferença entre uma mudança que quebra algo e uma que não quebra?</strong> Uma mudança que quebra algo obriga um chamador correto a mudar seu código, sua configuração ou seus dados para continuar funcionando. Uma mudança que não quebra deixa toda chamada existente funcionando com o mesmo significado, e é por isso que adições costumam ser seguras e remoções, renomeações e regras mais apertadas costumam não ser.</p> <p><strong>Adicionar um campo obrigatório conta?</strong> Sim. Toda chamada existente o omite, então toda chamada existente falha agora. Adicione-o como opcional com um padrão sensato, ou versione o endpoint.</p> <p><strong>Uma correção de bug conta?</strong> Pode ser. Se chamadores dependiam do comportamento com bug, corrigi-lo os quebra, não importa o que a documentação dizia. Trate qualquer correção que muda a saída observável como quebrando algo, a menos que você possa mostrar que ninguém dependia dela.</p> <p><strong>Versionamento semântico se aplica a uma API web?</strong> A regra sim: mudanças que quebram algo recebem uma nova versão major e a antiga continua funcionando por um período declarado. O número frequentemente vive na URL ou em um header de data em vez de em uma versão de pacote.</p> <p><strong>Quanto aviso é suficiente?</strong> O suficiente para um chamador encontrar o aviso e fazer o trabalho. Noventa dias é um piso comum para APIs públicas; mais longo para qualquer coisa usada em código que é enviado a usuários finais e não pode ser atualizado remotamente.</p> </article> <article> <h1>Fechar o ciclo de feedback pelo changelog</h1> <p>Sat, 29 Aug 2026 00:00:00 GMT</p> <p>Um ciclo de feedback do cliente é fechado quando a pessoa que deu o feedback recebe a informação do que aconteceu com ele. Não quando é registrado. Não quando é priorizado. Nem quando é lançado. Quando é dito a ela. A maioria das equipes faz bem os três primeiros passos e o último nem um pouco, e depois se pergunta por que as pessoas que mandam feedback param de mandar.</p> <p>Este artigo trata desse último passo, e de uma afirmação concreta: o changelog é o lugar certo para fechar o ciclo, porque é o único artefato que já existe exatamente no momento em que o ciclo pode ser fechado.</p> <h2>O que é um ciclo de feedback do cliente?</h2> <p>Um ciclo de feedback do cliente é o caminho de uma usuária dizendo algo a vocês até essa usuária descobrir o que vocês fizeram a respeito. Tem quatro passos: coletar o feedback, decidir o que fazer com ele, lançar o resultado, e avisar a pessoa que pediu. O ciclo está aberto até o quarto passo acontecer. Uma equipe que coleta feedback e lança correções mas nunca avisa ninguém tem uma caixa de entrada, não um ciclo.</p> <table> <thead> <tr> <th>Passo</th> <th>O que acontece</th> <th>Onde geralmente quebra</th> </tr> </thead> <tbody><tr> <td>Coletar</td> <td>Feedback chega: widget, suporte, vendas, entrevistas</td> <td>Nada; toda equipe faz isso</td> </tr> <tr> <td>Decidir</td> <td>É triado, fundido com duplicatas, aceito ou rejeitado</td> <td>Rejeições nunca são comunicadas</td> </tr> <tr> <td>Lançar</td> <td>Alguém constrói e vai ao ar</td> <td>O link para o pedido se perde no merge</td> </tr> <tr> <td>Avisar</td> <td>Quem pediu descobre que foi lançado</td> <td>Pulado, ou feito só para quem reclamou mais alto</td> </tr> </tbody></table> <p>A quarta linha é sobre o que este artigo trata. Ela quebra por uma razão estrutural, não cultural: no momento em que um recurso é lançado, o pedido que o causou vive em um sistema diferente da coisa lançada, e não é trabalho de ninguém conectá-los. O ciclo começa antes, com a forma como o pedido é feito logo de início; <a href="https://changeloop.dev/blog/pt-br/how-to-ask-for-customer-feedback/">como pedir feedback aos clientes</a> trata da redação e do momento certo.</p> <h2>Por que ciclos de feedback ficam abertos?</h2> <p>Ciclos de feedback ficam abertos porque o pedido e a mudança lançada vivem em lugares diferentes e o link entre os dois é feito manualmente, quando é feito. O pedido está em uma ferramenta de feedback, uma caixa de suporte ou uma planilha. A mudança está em um pull request. O anúncio está em um changelog ou um e-mail. Três sistemas, três donos, e o link do terceiro de volta ao primeiro é uma pessoa se lembrando, meses depois, quem pediu.</p> <p>Há uma segunda razão. O passo de avisar geralmente é enquadrado como uma tarefa de marketing ("anunciar o recurso") em vez de uma tarefa de suporte ("responder à pessoa"). Anúncios vão para todo mundo e não alcançam ninguém em particular. A pessoa que pediu o recurso em março lê o anúncio em junho, se ler, como notícia, não como resposta. O ciclo só fecha se a mensagem for direcionada a ela.</p> <h2>Por que fechar o ciclo pelo changelog?</h2> <p>Porque a entrada de changelog é o único artefato que existe exatamente no momento certo, contém exatamente as palavras certas, e é escrita exatamente pela pessoa certa. Ela existe quando a mudança está no ar e não antes. Ela diz o que mudou nos termos da leitora, que é a mensagem de que a pessoa que pediu precisa. E é escrita por alguém que acabou de ler o pull request, que é o único momento em que o link para o pedido original ainda está visível.</p> <p>Compare as alternativas. Fechar o ciclo pela ferramenta de feedback significa que a ferramenta de feedback precisa saber quando o recurso foi lançado, o que significa que alguém atualiza um status manualmente. Fechá-lo pelo pull request significa avisar a cliente no merge, antes que a mudança esteja no ar, uma promessa quebrada com carimbo de tempo assim que o deploy atrasa. Fechá-lo pelo anúncio de marketing significa esperar por um, e a maioria das mudanças lançadas nunca recebe um.</p> <p>O changelog fica no meio: depois do merge, no momento do lançamento, com a formulação pronta.</p> <h2>Como o ciclo fecha, passo a passo</h2> <p>Este é o mecanismo que rodamos. É descrito aqui como uma especificação em vez de um tour de produto, porque cada passo pode ser feito manualmente ou com outras ferramentas; o que importa é a ordem.</p> <ol> <li><strong>O feedback vira uma issue no repositório que vai corrigi-lo.</strong> Um envio de widget é registrado como uma issue etiquetada no GitHub (<code>feature-request</code> ou <code>bug</code>, uma prioridade, e <code>from-widget</code>), com o endereço de e-mail de quem enviou mantido fora do corpo da issue. A issue vive junto do código, para que o passo três possa encontrá-la. Uma issue aberta manualmente, por exemplo a partir de um <a href="https://changeloop.dev/blog/pt-br/feature-request-template/">template de solicitação de recurso</a>, fica fora desse caminho: o passo cinco não comenta nela, então feche esse ciclo você mesmo.</li> <li><strong>A correção referencia a issue.</strong> O pull request diz <code>Fixes #142</code>, a própria palavra-chave de fechamento do GitHub. Nada novo para aprender, e é a mesma frase que desenvolvedores já escrevem.</li> <li><strong>A entrada de changelog é redigida a partir do pull request mergeado e carrega o link.</strong> No merge, o rascunho é criado e <code>#142</code> é lido do corpo da PR e anexado ao rascunho. O link é criado enquanto ainda é barato, por uma máquina, a partir de dados que já estão lá.</li> <li><strong>Uma pessoa revisa a entrada.</strong> Formulação, público, se deveria ser publicada. Um rascunho descartado não fecha nada, o que é correto: um refactor interno que por acaso referenciou uma issue não é notícia.</li> <li><strong>Na aprovação, quem pediu é avisado.</strong> Um comentário é publicado na issue em que o feedback dessa pessoa se transformou, "Shipped —" seguido do título da entrada e um link para a entrada publicada, e o widget mostra a quem enviou a mesma entrada lançada. Uma vez, nunca duas, e só depois que uma pessoa publicou a entrada. A mesma entrada sai por <a href="https://changeloop.dev/docs">feed e widget</a> para todo mundo que não pediu.</li> </ol> <p>A ordem no passo cinco é todo o design. Avisar quem pediu no merge seria mais cedo e mais fácil, e estaria errado aproximadamente tão frequentemente quanto deploys atrasam. Um feature flag quebra até essa ordem, porque aprovado e publicado pode acontecer enquanto a funcionalidade ainda está invisível para a conta de quem pediu; <a href="https://changeloop.dev/blog/pt-br/feature-flags-feature-requests/">feature flags e pedidos de funcionalidades</a> cobre a verificação extra que esse passo precisa assim que um flag entra em cena.</p> <h2>Como um ciclo fechado parece para a cliente?</h2> <p>Parece uma resposta. A cliente mandou um pedido por um widget, e um dia o widget o mostra como lançado, com link para uma entrada que o descreve nos termos dela; no GitHub, a issue recebe a mesma notícia como comentário. Ela não assinou uma newsletter, não checou um roadmap, não procurou no changelog. Foi dito a ela.</p> <p>Essa é a experiência que faz o próximo pedaço de feedback acontecer. Pessoas mandam feedback para produtos que respondem. A página <a href="https://changeloop.dev/changelog-examples">exemplos de changelog</a> inclui entradas de equipes cujos usuários visivelmente continuam voltando com pedidos, e o fio comum não é a ferramenta; é que as entradas se leem como respostas.</p> <h2>Como se mede um ciclo de feedback?</h2> <p>Meça a fração de mudanças lançadas que avisaram pelo menos uma pessoa que pediu, e o tempo entre o lançamento e o aviso. Dois números, ambos fáceis assim que o link existe e impossíveis antes.</p> <ul> <li><strong>Taxa de fechamento</strong>: das entradas de changelog publicadas neste mês, quantas linkaram pelo menos um pedido, e dessas, quantas avisaram quem pediu. Se o segundo número for muito menor que o primeiro, notificações estão falhando; se o primeiro for baixo, pedidos não estão sendo referenciados a partir de pull requests, e a correção é uma frase no template de PR.</li> <li><strong>Tempo de lançamento até aviso</strong>: quanto tempo entre a entrada ir ao ar e o aviso a quem pediu. Com o mecanismo acima são segundos. Manualmente são tipicamente semanas, ou nunca, e "nunca" é o número que importa.</li> </ul> <p>Não meça o ciclo pelo volume de feedback coletado. Coletar é o passo fácil, e uma equipe que o mede vai otimizá-lo, o que produz mais ciclos abertos.</p> <h2>Onde o roadmap se encaixa?</h2> <p>Um roadmap público é uma forma de fechar o ciclo cedo: diz a quem pediu que o pedido foi ouvido, antes de ser lançado. É útil, e não substitui o último passo. "Planejado" é uma promessa sobre o futuro; "Lançado" é um fato sobre o presente. Rode o <a href="https://changeloop.dev/blog/pt-br/public-roadmap/">roadmap público</a> a partir das mesmas issues, com uma etiqueta por coluna, para que o mesmo pedido se mova de planejado para lançado sem ser reinserido em lugar nenhum. A mudança para lançado é uma troca de etiqueta (<code>roadmap:shipped</code>) que ninguém faz por você quando a entrada é aprovada, então faça isso na mesma revisão.</p> <h2>FAQ</h2> <p><strong>Quais são os quatro passos de um ciclo de feedback do cliente?</strong> Coletar, decidir, lançar, avisar. O ciclo está aberto até o quarto passo acontecer. A maioria dos frameworks adiciona passos de análise e priorização no meio; são refinamentos de "decidir", e nenhum deles fecha nada.</p> <p><strong>Deveria-se avisar clientes quando um pedido é rejeitado?</strong> Sim, e é a mensagem mais negligenciada do ciclo. Um claro "não vamos fazer isso, e aqui está o motivo" encerra a espera. Silêncio deixa o ciclo aberto para sempre e a cliente conferindo.</p> <p><strong>Como fechar o ciclo difere de anunciar um recurso?</strong> Um anúncio vai para todo mundo. Fechar o ciclo é uma resposta às pessoas que pediram, no canal por onde pediram. Faça ambos; são mensagens diferentes para leitoras diferentes.</p> <p><strong>E se quem pediu não está no GitHub?</strong> A maioria não está, e tudo bem. O widget continua mostrando a essas pessoas o status do que enviaram, incluindo a entrada lançada e o link dela, então elas não precisam de nada além da página de onde escreveram. O comentário na issue é para quem consegue ver o repositório.</p> <p><strong>Esse ciclo funciona no GitLab ou no Bitbucket em vez do GitHub?</strong> O widget e o changelog funcionam; o comentário automático do quinto passo não, hoje. Um time no GitLab ou no Bitbucket ainda recebe cada envio, ainda o registra como uma issue, e ainda mostra à pessoa que pediu um status no widget, mas fechar esse ciclo específico de volta na própria issue é um passo que se faz manualmente até essa integração existir.</p> </article> <article> <h1>Template de solicitação de recurso que vira changelog</h1> <p>Sat, 29 Aug 2026 00:00:00 GMT</p> <p>Um template de solicitação de recurso é um formulário com quatro perguntas: o que a pessoa está tentando fazer, o que a impede, o que ela tentou em vez disso, e como ela quer ser avisada quando estiver pronto. Tudo mais que geralmente aparece em um, seletores de prioridade, estimativas de esforço, pontuações de valor de negócio, é para a equipe que recebe a solicitação, e é preenchido incorretamente por quem envia.</p> <p>Solicitações organizadas são o teste errado para um template. O certo: seis meses depois, quando o recurso é lançado, alguém consegue encontrar a solicitação, entendê-la, e avisar a pessoa que a escreveu? A maioria dos templates é desenhada para admissão. Este é desenhado para o dia em que o ciclo fecha.</p> <h2>O que um template de solicitação de recurso deveria incluir?</h2> <p>Deveria incluir o objetivo, o bloqueio, a solução alternativa, e um caminho de volta para quem pediu. Quatro campos, nessa ordem, cada um responde a uma pergunta que a equipe fará depois.</p> <table> <thead> <tr> <th>Campo</th> <th>A pergunta que responde depois</th> <th>Por que está no formulário</th> </tr> </thead> <tbody><tr> <td>O que você está tentando fazer?</td> <td>O recurso construído era o que era necessário?</td> <td>O objetivo sobrevive a qualquer proposta concreta</td> </tr> <tr> <td>O que te impede hoje?</td> <td>Como é "pronto"?</td> <td>Nomeia a lacuna sem prescrever a correção</td> </tr> <tr> <td>O que você faz em vez disso?</td> <td>Quão urgente isso é de verdade?</td> <td>Uma solução alternativa dolorosa é um sinal mais forte que um seletor de prioridade</td> </tr> <tr> <td>Como devemos te avisar?</td> <td>Quem recebe a mensagem de "lançado"?</td> <td>O campo que a maioria dos templates omite</td> </tr> </tbody></table> <p>O que fica deliberadamente ausente: uma solução proposta como campo obrigatório (bem-vinda como comentário, errada como enquadramento), um seletor de prioridade (todo mundo que envia escolhe alta), e qualquer estimativa de esforço ou valor (trabalho da equipe, depois da triagem). Um template que pede uma solução recebe solicitações de botões; um template que pede um objetivo recebe solicitações de resultados, e sobre resultados é que se escreve uma entrada de changelog.</p> <h2>O template</h2> <p>Este é o template de issue do GitHub que usamos, como formulário. Cole-o em <code>.github/ISSUE_TEMPLATE/feature_request.yml</code> e ele renderiza como formulário estruturado na página de nova issue. Solicitações registradas através dele caem como issues com os mesmos campos das registradas por um widget de feedback, o que importa para a próxima seção.</p> <pre><code class="language-yaml">name: Feature request description: What you are trying to do, and what stops you. labels: ["feature-request"] body: - type: textarea id: goal attributes: label: What are you trying to do? description: >- The outcome, not the button. "Export a month of invoices as one PDF" beats "add a PDF export". validations: required: true - type: textarea id: blocker attributes: label: What stops you today? description: >- Where the product runs out. An error, a missing option, a limit. validations: required: true - type: textarea id: workaround attributes: label: What do you do instead? description: >- The spreadsheet, the script, the manual step. "Nothing, I gave up" is a valid answer. - type: input id: contact attributes: label: How should we tell you when it ships? description: >- An email address, or leave blank to be notified only on this issue. </code></pre> <p>Dois detalhes fazem o trabalho. <code>labels: ["feature-request"]</code> significa que a solicitação é classificada na criação em vez de esperar que alguém a triagem. E o último campo existe porque "vamos te avisar" é uma promessa, e uma promessa precisa de um endereço.</p> <h2>Quais etiquetas uma solicitação de recurso deveria carregar?</h2> <p>Uma solicitação de recurso deveria carregar uma etiqueta para o que ela é, uma para quão urgente é, e uma para de onde veio. Três etiquetas, três eixos, e cada uma é lida por uma leitora diferente.</p> <table> <thead> <tr> <th>Etiqueta</th> <th>Valores</th> <th>Quem lê</th> </tr> </thead> <tbody><tr> <td>Tipo</td> <td><code>feature-request</code>, <code>bug</code></td> <td>Quem decide em qual fila ela entra</td> </tr> <tr> <td>Prioridade</td> <td><code>priority:low</code>, <code>priority:medium</code>, <code>priority:high</code></td> <td>Quem planeja o próximo ciclo</td> </tr> <tr> <td>Origem</td> <td><code>from-widget</code>, <code>from-form</code>, <code>from-support</code></td> <td>Quem mede de onde vêm as solicitações</td> </tr> </tbody></table> <p>O widget aplica os dois primeiros eixos e <code>from-widget</code> quando registra um envio como issue; <code>from-form</code> e <code>from-support</code> são sugestões para solicitações que chegam por outros caminhos. As etiquetas do widget são um tipo (<code>bug</code> ou <code>feature-request</code>, decidido por um classificador só a partir da mensagem), uma prioridade (um relato de falha calmo e específico é alto; um duplicado de algo já perguntado é baixo; qualquer coisa que sequer sugira um problema de segurança é <code>bug</code> e alto, independente da formulação), e <code>from-widget</code>. Os mesmos três eixos funcionam para solicitações que chegam manualmente através do template acima, e esse é o ponto: uma solicitação é uma solicitação, não importa por onde entrou.</p> <p>Mais uma convenção: o widget remove o endereço de e-mail de quem enviou do corpo da issue antes de registrá-la, porque a issue vive em um repositório que pode ser público, e o substitui por uma referência de envio. O endereço fica fora da issue; quem enviou acompanha o resultado no próprio widget. Faça o mesmo com o campo de contato se seu tracker for visível para pessoas fora da equipe.</p> <h2>Como uma solicitação de recurso vira uma entrada de changelog?</h2> <p>Uma solicitação de recurso vira uma entrada de changelog quando um pull request fecha a issue e a entrada redigida a partir desse pull request linka de volta. O mecanismo são as próprias palavras-chave de fechamento do GitHub: uma PR cuja descrição diz <code>Fixes #142</code> fecha a issue 142 no merge. Se suas entradas de changelog são redigidas a partir de pull requests mergeados, o rascunho pode carregar o número da issue com ele, e a entrada sabe quem pediu.</p> <p>Essa é a razão pela qual o template pede o objetivo em vez da solução. Quando a entrada é escrita, o objetivo é a frase de que quem escreve precisa: "Agora você pode exportar um mês de faturas como um único PDF" é uma entrada de changelog. "Adicionado export de PDF" é uma mensagem de commit. As <a href="https://changeloop.dev/changelog-tools">ferramentas de changelog</a> que redigem a partir de pull requests podem fazer a coleta e o link; a formulação ainda precisa de uma pessoa, e a pessoa precisa do objetivo.</p> <h2>O que acontece quando é lançado?</h2> <p>Quem pediu é avisado, com um link para a entrada. No nosso setup isso é automático para solicitações que chegaram pelo widget: um comentário dizendo "Shipped — <título da entrada>" com um link para a entrada publicada, postado na issue assim que uma pessoa aprova a entrada, enquanto o widget mostra a mesma entrada para quem enviou. Uma issue aberta manualmente a partir deste template não recebe comentário automático; feche esse ciclo você mesmo, pela mesma regra. O comentário é postado deliberadamente na aprovação em vez de no merge: um comentário dizendo que algo está no ar antes de estar é uma promessa quebrada com carimbo de tempo. Cada solicitação é notificada no máximo uma vez; uma segunda aprovação da mesma entrada não produz um segundo comentário.</p> <p>Se vocês fazem isso manualmente, a mesma regra se aplica. Não fechem o ciclo pelo pull request. Fechem-no pela entrada publicada, e fechem uma vez. <a href="https://changeloop.dev/docs">Feed e widget</a> levam a mesma entrada para todo mundo que não pediu, que são a maioria; o comentário é para quem pediu.</p> <h2>Por que a maioria dos templates de solicitação de recurso falha</h2> <p>Eles são desenhados para facilitar a triagem e conseguem, ao custo do único momento que importa para quem pediu. Um template com doze campos recebe menos solicitações, e as que recebe vêm de pessoas com a paciência de preencher doze campos, o que não é a mesma população de quem precisa do recurso. Um template com quatro campos, um dos quais é "como te contatamos", recebe mais solicitações e pode honrar todas elas.</p> <h2>FAQ</h2> <p><strong>Um template de solicitação de recurso deveria perguntar sobre prioridade?</strong> Não. Pergunte sobre a solução alternativa em vez disso. "Eu exporto para uma planilha e redigito toda sexta-feira" diz mais sobre prioridade do que um menu suspenso que quem enviou marcou como alta.</p> <p><strong>Quem pede deveria propor uma solução?</strong> Pode, no texto livre. Não faça disso o enquadramento. Solicitações escritas como soluções são mais difíceis de fundir umas com as outras e mais difíceis de transformar em uma entrada de changelog.</p> <p><strong>Solicitações de recurso deveriam aparecer em um roadmap público?</strong> Uma vez planejadas, sim: uma etiqueta na mesma issue a coloca na coluna planejado, e quem pediu pode ver como ela se move. O artigo <a href="https://changeloop.dev/blog/pt-br/public-roadmap/">roadmap público</a> é o mecanismo.</p> <p><strong>Como lidar com duplicatas?</strong> Vincule a nova solicitação à issue existente e marque com prioridade baixa; não a feche. Cada duplicata é mais uma pessoa para avisar quando for lançado. Com o comentário automático do Changeloop, essa pessoa só é avisada se o pull request também nomear a issue dela (<code>Fixes #142, fixes #187</code>).</p> <p><strong>Onde o template deveria viver?</strong> No repositório que vai receber o pull request, para que a palavra-chave de fechamento funcione. Uma solicitação em um tracker separado precisa ser vinculada manualmente no merge, e é esse o passo que é pulado.</p> </article> <article> <h1>Roadmap público a partir do seu issue tracker, três colunas</h1> <p>Sat, 29 Aug 2026 00:00:00 GMT</p> <p>Um roadmap público é uma lista do que vocês pretendem construir, publicada onde clientes podem vê-la. A palavra que faz o trabalho é <em>pretendem</em>: um roadmap é um conjunto de promessas sobre o futuro, e cada item nele é um que vocês vão cumprir ou será visto que não cumpriram. Essa é a razão para publicar um, e é também a razão pela qual a maioria dos roadmaps públicos envelhece em um trimestre. A versão que sobrevive é pequena, derivada de dados que vocês já mantêm, e conectada na outra ponta ao changelog, para que uma promessa vire um fato sem que ninguém a reinsira.</p> <h2>Para que serve um roadmap público?</h2> <p>Um roadmap público diz a uma cliente com um pedido que o pedido foi ouvido, antes de ser lançado. É a metade inicial do fechamento do ciclo: "Planejado" responde a pergunta "alguém leu isso", e "Em construção" responde "isso está realmente acontecendo". Nenhum dos dois substitui o último passo, avisar quem pediu quando for lançado, mas ambos reduzem o número de pessoas que perguntam enquanto isso.</p> <p>Também faz algo pela equipe: força um compromisso público, que é o remédio mais barato conhecido para um backlog que silenciosamente guarda quatrocentos itens que ninguém vai construir.</p> <table> <thead> <tr> <th>Coluna</th> <th>A promessa que faz</th> <th>O que move um item para dentro</th> </tr> </thead> <tbody><tr> <td>Planejado</td> <td>Pretendemos construir isso</td> <td>Uma decisão, registrada como etiqueta na issue</td> </tr> <tr> <td>Em construção</td> <td>Alguém está trabalhando nisso agora</td> <td>Uma etiqueta <code>roadmap:building</code> na issue</td> </tr> <tr> <td>Lançado</td> <td>Está no ar</td> <td>Uma etiqueta <code>roadmap:shipped</code>, ou fechar a issue enquanto ela tem essa etiqueta</td> </tr> </tbody></table> <p>Três colunas, em ordem fixa, bastam. Uma quarta coluna ("em consideração", "em revisão", "backlog") é onde boas intenções viram um museu, e é a primeira que clientes aprendem a ignorar.</p> <h2>Seu roadmap deveria ser público?</h2> <p>Torne-o público se vocês conseguem mantê-lo pequeno e honesto; mantenha-o privado se a alternativa é uma longa lista de talvez. O custo de um roadmap público não tem nada a ver com publicá-lo: todo item nele agora é uma pergunta que alguém vai fazer, no suporte, em ligações de vendas e em conversas de renovação. Dez itens que vocês vão construir são um ativo. Sessenta itens que vocês talvez construam são sessenta conversas futuras sobre por que não.</p> <p>Duas razões honestas para não publicar: os planos de vocês mudam mais rápido que um trimestre, ou a concorrência de vocês lê o roadmap com mais cuidado que seus clientes. Ambas são reais, e ambas são respondidas publicando menos em vez de nada: só "em construção", com "planejado" mantido interno, ainda diz a quem pediu que a issue dele está se movendo.</p> <h2>Como se constrói um roadmap público a partir de issues do GitHub?</h2> <p>Coloque uma etiqueta por coluna nas issues que vocês já acompanham, e renderize as issues etiquetadas como o roadmap. Nada é reinserido, o roadmap não consegue se desviar do trabalho, e a mesma issue que começou como um pedido de cliente se move pelas colunas sem mudar de identidade.</p> <p>O mecanismo, do jeito que rodamos:</p> <ol> <li><strong>Uma etiqueta por coluna, com prefixo fixo</strong>: <code>roadmap:planned</code>, <code>roadmap:building</code>, <code>roadmap:shipped</code>. Qualquer issue em um repositório conectado que carregue uma aparece nessa coluna. Uma issue sem nenhuma delas não está no roadmap, o que é a maioria das issues, o que é correto.</li> <li><strong>As colunas são um array ordenado, sempre na mesma ordem.</strong> Planejado, em construção, lançado. Não um mapa indexado por nome, para que uma leitora (ou um widget) nunca tenha que adivinhar a sequência.</li> <li><strong>Se uma issue carrega duas etiquetas, a mais avançada vence.</strong> Alguém vai adicionar <code>roadmap:shipped</code> antes de remover <code>roadmap:planned</code>; uma máquina de estados guiada por "qual webhook chegou por último" colocaria o item em colunas diferentes dependendo da ordem de entrega. Decidir só a partir do conjunto de etiquetas faz a resposta ser a mesma independente de como os eventos chegam.</li> <li><strong>Lançado é um estado de etiqueta como os outros.</strong> O cartão se move quando a issue recebe <code>roadmap:shipped</code>, ou é fechada enquanto tem essa etiqueta. O cartão em si não linka para a entrada de changelog; a entrada, redigida a partir do pull request que fechou a issue, é onde ficam os detalhes.</li> <li><strong>Sirvam como dados.</strong> O roadmap é um documento JSON com essas três colunas, publicado ao lado do feed de changelog com os mesmos headers de cache, para que um site de docs, um widget ou uma página de status possam renderizá-lo sem uma segunda integração. A <a href="https://changeloop.dev/docs">documentação do feed</a> tem a forma exata.</li> </ol> <p>Uma etiqueta é pouco a pedir de uma mantenedora, e é toda a integração. Nenhum quadro para manter sincronizado, nenhuma ferramenta separada para fazer login, e o pedido que a cliente registrou é o item no roadmap; quando é lançado, é o mesmo item.</p> <h2>O que um roadmap público não deveria conter?</h2> <p>Não deveria conter datas, estimativas, ou qualquer coisa que envergonharia vocês se perguntassem daqui a nove meses. Datas são o erro clássico: um trimestre em um roadmap vira um compromisso em um deck de vendas vira um ticket chamado "vocês disseram Q3". Colunas dizem o suficiente. "Em construção" já significa "logo o bastante para que alguém esteja nisso".</p> <p>Também não deveria conter o backlog interno. Um roadmap com trezentos itens é um problema de busca, não uma promessa, e a cliente que encontra seu pedido na posição 212 aprendeu algo que vocês não queriam dizer a ela.</p> <h2>Como o roadmap se conecta ao changelog?</h2> <p>O roadmap e o changelog descrevem as mesmas issues de dois lados, um para o futuro e um para o passado. Ninguém move um cartão em um quadro separado. Uma mantenedora muda a etiqueta na issue em que já estava trabalhando, a entrada é redigida a partir do pull request, e quando uma pessoa aprova essa entrada, quem pediu e teve o feedback do widget transformado nessa issue é informado nela. Mover o cartão para lançado continua sendo um passo à parte, a etiqueta <code>roadmap:shipped</code>, então façam isso na mesma revisão; aprovar a entrada não faz isso por vocês.</p> <p>Este é o mesmo ciclo que o <a href="https://changeloop.dev/blog/pt-br/customer-feedback-loop/">artigo do ciclo de feedback</a> descreve pelo lado do changelog; o roadmap é o que a cliente vê no meio disso. O resumo <a href="https://changeloop.dev/changelog-tools">ferramentas de changelog</a> cobre quais produtos oferecem uma visão de roadmap e quais o tratam como um quadro separado, o que é a diferença que decide se ele permanece preciso.</p> <h2>Como se parece um bom roadmap público?</h2> <p>Parece curto, e todo item nele é uma issue que qualquer um pode abrir. O teste é se uma cliente consegue ir de um item para a discussão por trás dele, e de um item lançado para a entrada que descreve o que realmente mudou. Um roadmap que é uma lista de nomes de recursos sem entrada é um folheto.</p> <p>Um exemplo trabalhado, como o JSON que um widget buscaria:</p> <pre><code class="language-json">{ "columns": [ { "column": "planned", "hasMore": false, "items": [ { "id": "6b0c1f...", "column": "planned", "publicTitle": "Saved views on the inbox", "publicDescription": "Keep a filter you use often and come back to it.", "publishedAt": "2026-09-16T10:04:11.000Z" } ]}, { "column": "building", "hasMore": false, "items": [ { "id": "71a4e2...", "column": "building", "publicTitle": "Roadmap column in the widget", "publicDescription": "See what is coming without leaving the page.", "publishedAt": "2026-09-12T08:20:02.000Z" } ]}, { "column": "shipped", "hasMore": false, "items": [ { "id": "5c9d70...", "column": "shipped", "publicTitle": "Feedback filed as labelled issues", "publicDescription": "Widget submissions arrive as issues your triage already handles.", "publishedAt": "2026-09-02T15:41:37.000Z" } ]} ], "enabled": true, "language": "en" } </code></pre> <p>Três itens em três colunas são um roadmap público perfeitamente bom. Diz o que está por vir, o que está acontecendo, e o que aconteceu, e cada linha dele é verificável. Outros cinco layouts, de Now/Next/Later a roadmaps por resultados, aparecem com itens de exemplo em <a href="https://changeloop.dev/blog/pt-br/product-roadmap-examples/">exemplos de roadmap de produto</a>.</p> <h2>FAQ</h2> <p><strong>Quantos itens um roadmap público deveria ter?</strong> O menos possível que vocês consigam defender. Menos de dez no total é normal para um produto pequeno; mais de trinta em "planejado" geralmente é um backlog disfarçado de roadmap.</p> <p><strong>Um roadmap público deveria ter datas?</strong> Não. Colunas comunicam sequência sem criar um prazo. Se uma cliente precisa de uma data, isso é uma conversa, não um item de roadmap.</p> <p><strong>Clientes deveriam votar em itens do roadmap?</strong> Votos medem quem apareceu, não o que importa. Um comentário na issue explicando a solução alternativa que usam hoje vale mais que cinquenta votos, e custa algo a quem vota, que é o ponto.</p> <p><strong>O que acontece com um item de roadmap cancelado?</strong> Remova a etiqueta e diga o porquê na issue. Um "não vamos fazer isso" público faz parte do ciclo, e é a mensagem que a maioria das equipes nunca envia.</p> </article> <article> <h1>Automação de changelog, e seus limites</h1> <p>Fri, 28 Aug 2026 00:00:00 GMT</p> <p>Automação de changelog funciona quando automatiza coleta, classificação e publicação, e para em seleção e formulação. Automatize tudo e você entrega um git log formatado; não automatize nada e o changelog é escrito em rajadas, de memória, antes das releases. A pergunta útil é quais partes automatizar, não quanto.</p> <p>Projetos de automação de changelog falham em uma de duas direções, e ambas são previsíveis desde a primeira reunião de design. Automatize pouco demais e o changelog é um documento que alguém deveria atualizar, o que significa que é atualizado em rajadas, por quem tirou o palito mais curto. Automatize demais e vira um git log formatado: completo, preciso, e lido por ninguém.</p> <h2>Quais partes de um changelog deveriam ser automatizadas?</h2> <p>Três das quatro etapas. Coleta e publicação completamente; classificação como uma primeira passada com override humano; seleção e formulação nunca.</p> <table> <thead> <tr> <th>Etapa</th> <th>Automatizar?</th> <th>Por quê</th> </tr> </thead> <tbody><tr> <td>Coleta: mudanças de commits, PRs, tickets para uma lista</td> <td>Completamente</td> <td>Tedioso, pulado sob prazo, máquinas fazem perfeitamente</td> </tr> <tr> <td>Classificação: Added, Fixed, Changed, Deprecated, Removed, Security</td> <td>Primeira passada, override humano</td> <td>Cerca de 80% certo só com metadados; os 20% errados são as entradas que importam</td> </tr> <tr> <td>Seleção e formulação: o que dizer ao leitor, e como</td> <td>Nunca</td> <td>Este é todo o valor do artefato</td> </tr> <tr> <td>Publicação: página, feed, e-mail, widget, Slack</td> <td>Completamente, de uma fonte</td> <td>Onde vai a maior parte do esforço manual real</td> </tr> </tbody></table> <p><strong>Coleta.</strong> Tirar as mudanças de onde elas acontecem (commits, PRs, tickets) e colocá-las em uma lista. Automatize isso completamente. Humanos são ruins nisso, é tedioso, e é a etapa que é pulada sob prazo. <a href="https://changeloop.dev/blog/pt-br/conventional-commits-changelog/">Conventional commits</a> ou labels de PR são a matéria-prima usual.</p> <p><strong>Classificação.</strong> Decidir se algo é Added, Fixed, Changed, Deprecated, Removed ou Security. Automatize a primeira passada a partir do tipo de commit ou label da PR, e deixe um humano fazer override. A precisão aqui fica em torno de oitenta por cento só com metadados, e os vinte por cento errados se concentram exatamente nas entradas que importam, porque ambiguidade correlaciona com importância.</p> <p><strong>Seleção e formulação.</strong> Decidir o que um leitor deveria saber e como dizer isso. <strong>Não automatize isso.</strong> É todo o valor do artefato. Tudo mais é logística.</p> <p><strong>Publicação.</strong> Levar as entradas finalizadas para uma página, um feed, um e-mail, um widget in-app, um canal do Slack. Automatize completamente, e a partir de uma fonte. É aqui que vai a maior parte do esforço manual real, e quase ninguém conta isso. É também a etapa que pode dizer à pessoa que pediu a mudança que ela foi lançada, que é todo o tema de <a href="https://changeloop.dev/blog/pt-br/customer-feedback-loop/">fechar o ciclo de feedback pelo changelog</a>. A metade de e-mail desse passo tem sua própria forma, em <a href="https://changeloop.dev/blog/pt-br/product-update-email/">o template de e-mail de atualização de produto</a>.</p> <p>Esse último ponto vale a pena refletir. Equipes tendem a ver o changelog como um problema de escrita, e então passam a maior parte do tempo em distribuição: copiando entradas para uma ferramenta de e-mail, reformatando para in-app, colando no Slack, atualizando uma página de docs. A escrita leva uma hora. A cópia leva uma hora por release, para sempre, e é a parte que uma máquina deveria ter.</p> <h2>O que acontece quando a linha se move?</h2> <p><strong>Mova-a para cima e você recebe um dump de git.</strong> Automação total a partir de commits produz <code>bump deps</code>, <code>fix flaky test</code>, <code>wip</code> e <code>address review comments</code> na frente dos clientes. Toda equipe que fez isso depois adicionou um filtro, e o filtro é uma etapa de seleção reintroduzida sob outro nome, com ergonomia pior.</p> <p><strong>Mova-a para baixo e você recebe rajadas.</strong> Coleta totalmente manual significa que entradas são escritas de memória no momento da release. Esse é o modo contra o qual <a href="https://changeloop.dev/blog/pt-br/keep-a-changelog-implemented/">Keep a Changelog</a> avisa logo de início, e se degrada silenciosamente: o changelog parece mantido até a semana em que ninguém teve tempo.</p> <h2>Como se parece um pipeline de automação de changelog?</h2> <p>Quatro etapas, com exatamente um portão humano, colocado onde um rascunho vira público.</p> <ol> <li>No merge, derive uma entrada rascunho da PR: tipo a partir de label ou prefixo de commit, título como primeiro rascunho, link de volta para a PR, autora registrada. Coloque-a em um balde não lançado.</li> <li>Qualquer um pode editar qualquer rascunho a qualquer momento, e editar é barato. A maioria recebe uma linha reescrita.</li> <li>Cortar uma release exige que toda entrada no balde esteja editada ou explicitamente marcada como interna. Este portão é todo o design. Sem ele, rascunhos são lançados sem edição na semana corrida.</li> <li>Publicar é um fan-out a partir do conjunto lançado: a página pública, o feed, o e-mail, o widget, o post do Slack. Uma fonte, várias renderizações, sem cópia.</li> </ol> <p>A etapa 3 é o único lugar onde uma pessoa é necessária, e leva cerca de dez minutos por release assim que os rascunhos estão decentes. Onde uma solicitação de cliente está envolvida, o rascunho também carrega a issue que ele fecha, que é o que permite à etapa 4 avisar quem pediu; o <a href="https://changeloop.dev/blog/pt-br/feature-request-template/">template de solicitação de recurso</a> é desenhado para que esse link sobreviva. Onde essa etapa se encaixa no fluxo de release mais amplo é o assunto do <a href="https://changeloop.dev/blog/pt-br/release-management-process/">processo de gerenciamento de releases</a>.</p> <h2>O que a automação exige dos seus dados?</h2> <p>Nada disso funciona se o changelog é um arquivo Markdown, porque um arquivo não pode ser renderizado em cinco superfícies sem ser reparseado, e parsear prosa é como você acaba com um widget que mostra metade de um título.</p> <p>Entradas precisam ser estruturadas: um tipo, uma data, uma versão ou identificador de release, um público, um corpo e um link. Aí o arquivo, a página, o feed e o e-mail são todos visões. Esse ponto estrutural é a única coisa que vale a pena acertar antes de escolher uma ferramenta, porque é o que você não consegue adicionar barato depois. Nada disso funciona se uma entrada não for de fato criada para cada mudança que precisa dela; <a href="https://changeloop.dev/blog/pt-br/changelog-ci-enforcement/">exigir uma entrada de changelog no CI</a> cobre como fazer o pipeline recusar um merge sem entrada, em vez de deixar esse passo por conta da memória.</p> <p>Nós construímos o <a href="https://changeloop.dev/">changeloop</a>, onde o changelog é primeiro um feed e depois uma página, então leia isso como um interesse em vez de uma recomendação imparcial; o <a href="https://changeloop.dev/pricing">pricing</a> é um repositório grátis sem cartão, suficiente para ver a forma. <a href="https://changeloop.dev/changelog-tools">Ferramentas de changelog</a> é nosso resumo do que mais existe, incluindo os produtos com os quais competimos, e o <a href="https://changeloop.dev/changelog-generator">gerador de changelog</a> faz as etapas de coleta e classificação no navegador se você quiser ver a derivação antes de se comprometer com um pipeline.</p> <h2>O teste</h2> <p>Conte os minutos entre uma mudança ser mergeada e essa mudança ficar visível para uma cliente que não lê o repo de vocês. Se a maioria desses minutos é alguém copiando texto entre ferramentas, a automação de que vocês precisam está na publicação, não na escrita.</p> <h2>FAQ</h2> <p><strong>A IA pode escrever o changelog?</strong> Ela pode redigir um. Um modelo ao qual se dá o pull request mergeado produz na maioria das vezes um primeiro rascunho utilizável do título e do corpo, o que é a coleta e a classificação feitas melhor. A seleção, se um leitor deveria saber algo, e a formulação final, ainda precisam da pessoa que conhece o público, e um pipeline que publica rascunhos sem esse portão automatizou a etapa errada.</p> <p><strong>Qual é a diferença entre um gerador de changelog e automação de changelog?</strong> Um gerador transforma commits em uma lista formatada uma vez, sob demanda. Automação roda a cada merge, mantém um balde não lançado, condiciona a release a revisão humana, e publica em cada superfície a partir de uma fonte. O gerador é a primeira etapa do pipeline, executada manualmente.</p> <p><strong>O changelog deveria ser automatizado a partir de commits ou de pull requests?</strong> De pull requests, onde a unidade de mudança é a PR: o título e a descrição são escritos uma vez, para toda a mudança, e a PR liga a issue que fecha. Derivação baseada em commits funciona quando o commit é a unidade e segue uma convenção.</p> <p><strong>Como se evita que a automação publique mudanças internas?</strong> Classifique <code>chore</code>, <code>ci</code>, <code>test</code>, <code>refactor</code> e atualizações de dependências como internas por padrão, e torne a promoção a público um ato deliberado. O padrão inverso, público a menos que alguém esconda, é como <code>bump deps</code> chega aos clientes.</p> </article> <article> <h1>Changelog vs release notes: qual é a diferença?</h1> <p>Fri, 28 Aug 2026 00:00:00 GMT</p> <p>Um changelog é um registro contínuo e cumulativo de tudo que mudou, escrito para alguém que está procurando algo. Release notes são uma mensagem selecionada sobre uma release, escrita para alguém que decide se isso importa para ele. A diferença é o público, não a formatação, e a maioria das equipes precisa de ambos: um como referência, outro como anúncio, derivados das mesmas entradas.</p> <p>A maioria das equipes acaba com um deles por acidente e o outro por solicitação. Você começa com um changelog porque uma desenvolvedora quer um registro do que foi lançado. Meses depois alguém do suporte pergunta por que os clientes não sabiam sobre um recurso que está no ar desde abril, e agora vocês precisam de release notes.</p> <h2>Changelog vs release notes, lado a lado</h2> <table> <thead> <tr> <th></th> <th>Changelog</th> <th>Release notes</th> </tr> </thead> <tbody><tr> <td>Leitor</td> <td>Alguém procurando algo</td> <td>Alguém decidindo se importa</td> </tr> <tr> <td>Escopo</td> <td>Tudo que mudou</td> <td>O que vale a pena dizer sobre esta release</td> </tr> <tr> <td>Cadência</td> <td>Contínua, por merge ou por release</td> <td>Por release, e só as que valem a pena anunciar</td> </tr> <tr> <td>Tom</td> <td>Conciso, factual, muitas vezes imperativo</td> <td>Explicativo, às vezes persuasivo</td> </tr> <tr> <td>Vida útil</td> <td>Permanente, lida anos depois</td> <td>Lida na primeira semana, depois arquivada</td> </tr> <tr> <td>Vive em</td> <td>O repo, um site de docs, uma página <code>/changelog</code></td> <td>E-mail, in-app, um post de blog, uma página de release</td> </tr> <tr> <td>Falha por</td> <td>Estar incompleto</td> <td>Ser chato, ou chegar tarde</td> </tr> </tbody></table> <h2>O que é um changelog?</h2> <p>Um changelog é um registro cronológico, quase completo, do que mudou, mais recente primeiro, com cada entrada tipada (added, changed, deprecated, removed, fixed, security) e datada. Seu leitor já decidiu que se importa. Ele está procurando algo: quando um comportamento mudou, se um bug foi corrigido, qual versão introduziu uma flag. Completude é todo o valor, por isso a convenção <a href="https://changeloop.dev/blog/pt-br/keep-a-changelog-implemented/">Keep a Changelog</a> gasta a maior parte de sua única página em estrutura e quase nada em prosa.</p> <h2>O que são release notes?</h2> <p>Release notes são uma mensagem seletiva, escrita em prosa, sobre uma release. Seu leitor ainda não decidiu nada. Ele está decidindo se esta release importa para ele, e se precisa fazer algo a respeito. Seleção é todo o valor: uma release note que lista tudo é um changelog com parágrafos, e falha o leitor da mesma forma que um changelog que pula coisas falha o seu. <a href="https://changeloop.dev/blog/pt-br/how-to-write-release-notes/">Como escrever release notes</a> trata da seleção e da formulação.</p> <h2>Você precisa de um changelog e de release notes?</h2> <p>Vocês precisam de ambos assim que os dois públicos quiserem coisas diferentes; até lá, um único artefato fazendo os dois trabalhos é correto. Equipes pequenas publicam uma única página <code>/changelog</code> com um parágrafo curto no topo de cada entrada, e por um tempo isso serve igualmente bem a uma desenvolvedora procurando uma correção e a uma cliente passando os olhos por novidades. Dividir cedo demais dá a vocês duas coisas para manter e uma delas vai apodrecer.</p> <p>A divisão vale a pena quando isso começa a acontecer:</p> <ul> <li>As entradas de changelog de vocês cresceram parágrafos explicativos que desenvolvedores pulam.</li> <li>Ou o oposto: os anúncios de release de vocês começaram a listar atualizações de dependências.</li> <li>O suporte está copiando entradas para e-mails e reescrevendo-as no caminho.</li> <li>Alguém pede "só as mudanças que quebram algo" e vocês não conseguem filtrar por isso.</li> </ul> <p>Esse último é o verdadeiro sinal. Se ninguém consegue responder "o que mudou que me afeta" sem ler tudo, vocês têm um artefato fazendo dois trabalhos mal.</p> <h2>Uma fonte, duas visões</h2> <p>O erro é tratá-los como dois documentos. São duas visões sobre o mesmo conjunto de mudanças.</p> <p>Escrevam o changelog ao longo do caminho, uma entrada por mudança significativa, cada uma marcada com o que é: fixed, added, changed, removed, deprecated, security. Mantenham as entradas curtas o suficiente para que escrever uma não seja uma decisão. Depois, no momento da release, release notes são uma seleção e uma reescrita: peguem as entradas que importam a uma pessoa, agrupem-nas pelo que permitem que alguém faça, e coloquem o motivo no topo.</p> <p>Isso tem uma consequência prática. Se o changelog é a fonte, ele precisa ser dados estruturados, não uma página mantida manualmente. Uma entrada precisa de um tipo, uma data, uma versão, e uma forma de dizer para quem é. Assim que tiver isso, a página pública, o widget in-app e o feed RSS ou JSON são três renderizações de uma coisa só, e ninguém reescreve nada no caminho até um cliente. Um e-mail de release notes pode citar a mesma entrada, a partir de qualquer ferramenta que envie os e-mails de vocês. <a href="https://changeloop.dev/blog/pt-br/changelog-automation/">Automação de changelog</a> trata de qual dessas etapas uma máquina deveria possuir. Esse é todo o argumento para tratar um changelog como um feed em vez de uma página. É também, com total transparência, o que construímos, então leiam isso como um interesse em vez de uma pesquisa imparcial.</p> <h2>Se você só tiver tempo para um</h2> <p>Escrevam o changelog. É mais barato por entrada, é útil no dia em que você o escreve, e release notes podem ser derivadas dele depois. O contrário não é verdade: vocês não conseguem reconstruir um ano de mudanças a partir de doze e-mails de anúncio, e as pessoas vão pedir isso a vocês.</p> <p>Mantenham-no em um formato fixo para que a derivação continue possível. Nossa página <a href="https://changeloop.dev/changelog-examples">exemplos de changelog</a> reúne entradas de equipes que fazem isso bem, e o <a href="https://changeloop.dev/release-notes-template">template de release notes</a> é a forma que usamos ao transformar um conjunto de entradas em algo que vale a pena enviar.</p> <h2>Uma nota sobre nomenclatura</h2> <p>Nada disso é padronizado, e vocês vão encontrar "release notes" usado para uma lista contínua e "changelog" usado para um anúncio trimestral. Discutir sobre as palavras não vale a pena. Decidam qual dos dois trabalhos cada um dos artefatos de vocês está fazendo, nomeiem-no como sua equipe já chama, e garantam que nenhum dos dois esteja silenciosamente fazendo os dois.</p> <p>Em que superfície o resultado acaba é uma decisão separada, coberta em <a href="https://changeloop.dev/blog/pt-br/changelog-page/">como construir uma página de changelog</a>.</p> <h2>FAQ</h2> <p><strong>Um changelog é o mesmo que release notes?</strong> Não. Um changelog é o registro completo, lido por quem procura algo; release notes são o anúncio selecionado, lido por quem decide se importa. A mesma mudança aparece em ambos, formulada diferentemente para cada leitor.</p> <p><strong>Release notes podem ser geradas a partir de um changelog?</strong> Sim, e essa é a direção certa. Selecione as entradas que importariam a uma pessoa, agrupe-as por resultado, reescreva o título. O contrário, reconstruir um changelog a partir de anúncios, perde tudo que os anúncios deixaram de fora.</p> <p><strong>Onde um changelog deveria viver?</strong> Em algum lugar permanente e linkável que o leitor possa alcançar sem um repositório: uma página <code>/changelog</code>, um site de docs, ou um feed que é renderizado em vários lugares. Um <code>CHANGELOG.md</code> sozinho alcança colaboradores, não clientes.</p> <p><strong>Um changelog deveria incluir mudanças internas?</strong> Sim, no final, uma linha cada. O changelog é o registro completo. As release notes também podem mantê-las, em uma seção final curta, desde que as mudanças que o leitor vai notar venham primeiro.</p> </article> <article> <h1>Dos conventional commits a um changelog</h1> <p>Fri, 28 Aug 2026 00:00:00 GMT</p> <p>Conventional commits dão de graça a um changelog três coisas: o tipo de cada mudança, a parte do sistema que ela tocou, e se quebra algo. Não dão mais nada. Formulação, agrupamento e seleção, que são o changelog, ficam completamente abertos, e um pipeline que finge o contrário entrega um git log formatado.</p> <pre><code>feat(exports): add CSV column selection fix(auth): reject expired refresh tokens chore(deps): bump node-pg to 8.11 </code></pre> <p>Três commits no formato <a href="https://www.conventionalcommits.org/">Conventional Commits</a>. A partir desses, uma máquina consegue dizer que um é um recurso, um é uma correção, um é limpeza, e qual parte do sistema cada um tocou. Isso é genuinamente útil, e é toda a promessa da convenção: um histórico de commits que pode ser lido por algo além de uma pessoa. O erro é pensar que isso te dá um changelog. Te dá a matéria-prima.</p> <h2>O que a convenção especifica?</h2> <p>Um tipo, um scope opcional, e uma descrição: <code>type(scope): description</code>. Os tipos são convencionalmente <code>feat</code>, <code>fix</code>, <code>chore</code>, <code>docs</code>, <code>refactor</code>, <code>test</code>, <code>perf</code>, <code>build</code>, <code>ci</code>. Duas coisas marcam uma mudança que quebra algo: um <code>!</code> antes dos dois pontos, ou um footer <code>BREAKING CHANGE:</code>. As ferramentas se baseiam em <code>feat</code> e <code>fix</code> para incrementos de versão minor e patch, e no marcador breaking para um major.</p> <table> <thead> <tr> <th>O commit te dá</th> <th>O changelog precisa de</th> <th>Quem preenche a lacuna</th> </tr> </thead> <tbody><tr> <td><code>feat</code> / <code>fix</code> / <code>chore</code></td> <td>Added / Fixed / interno</td> <td>Um mapeamento, automático</td> </tr> <tr> <td><code>(scope)</code></td> <td>Um agrupamento que o leitor reconhece</td> <td>Uma pessoa, uma vez por scope</td> </tr> <tr> <td><code>!</code> ou <code>BREAKING CHANGE:</code></td> <td>Quem quebra, até quando, e o que fazer</td> <td>Uma pessoa, toda vez</td> </tr> <tr> <td>A descrição, escrita para uma revisora</td> <td>O resultado, escrito para uma cliente</td> <td>Uma pessoa, cada entrada</td> </tr> <tr> <td>Um commit</td> <td>Uma mudança, que pode ser vários commits</td> <td>Regras de squash, ou uma pessoa</td> </tr> </tbody></table> <p>O marcador conta para a ferramenta; não conta para quem chama, que é o assunto de <a href="https://changeloop.dev/blog/pt-br/api-deprecation/">como depreciar uma API</a> e <a href="https://changeloop.dev/blog/pt-br/breaking-changes/">o que é uma mudança que quebra algo</a>. É uma especificação pequena e vale a pena segui-la mesmo que você nunca gere nada a partir dela, porque força uma decisão por commit: isso é uma mudança que os usuários veem, ou não.</p> <h2>Onde os conventional commits param?</h2> <p>Eles param na frase. Tudo que a convenção captura é metadado sobre uma mudança; a mudança em si ainda é descrita no vocabulário de uma revisora.</p> <p><strong>Mensagens de commit são escritas para revisoras.</strong> <code>fix(auth): reject expired refresh tokens</code> está correto e não diz nada a uma cliente. A leitora de um changelog quer "você será deslogado quando uma sessão realmente tiver expirado, em vez de ver 401 intermitentes".</p> <p><strong>Scopes são internos.</strong> <code>exports</code>, <code>auth</code>, <code>ingest</code> são nomes de módulos. São estáveis, o que os torna bons para agrupar, e sem significado para quem está fora da base de código.</p> <p><strong>Uma mudança geralmente é vários commits.</strong> Um recurso mergeado em onze commits produz onze entradas, dez das quais ruído, e esmagá-las para esconder isso perde o histórico de revisão.</p> <p><strong><code>chore</code> é uma gaveta, não uma categoria.</strong> Atualizações de dependências, mudanças de CI e renomeações caem todas lá, e algumas importam para usuários enquanto a maioria não.</p> <p>Então: a convenção te dá tipo, scope e status de breaking de graça, e deixa formulação, agrupamento e seleção completamente abertos. Esses três são o changelog. <a href="https://changeloop.dev/blog/pt-br/changelog-entry-ownership/">Quem é realmente responsável por uma entrada de changelog</a> cobre quem deveria cuidar dessa formulação, agrupamento e seleção, já que a convenção em si não tem opinião sobre isso.</p> <h2>Como se gera um changelog a partir de conventional commits?</h2> <p>Em duas camadas, e a segunda tem que ser obrigatória.</p> <p><strong>Camada um, automática.</strong> No merge, derive uma entrada rascunho do commit: tipo mapeado para um tipo de changelog (<code>feat</code> para Added, <code>fix</code> para Fixed, um marcador breaking para Changed mais uma flag), scope mantido como metadado em vez de texto, link para a PR. Coloque-a na seção Unreleased que o <a href="https://changeloop.dev/blog/pt-br/keep-a-changelog-implemented/">Keep a Changelog</a> pede.</p> <p><strong>Camada dois, humana, e obrigatória.</strong> Antes que uma release saia, cada entrada rascunho recebe ou uma reescrita de uma linha no vocabulário do usuário, ou é marcada como interna e removida da visão pública. Este é o passo que as pessoas tentam pular, e pular é o que produz changelogs que se leem como um diff.</p> <p>O detalhe importante de design é que a camada dois não é opcional no pipeline. Se uma release pode ser cortada com rascunhos não editados, ela será, na semana em que todo mundo está ocupado. Quais etapas pertencem à máquina e quais à pessoa é todo o assunto de <a href="https://changeloop.dev/blog/pt-br/changelog-automation/">automação de changelog</a>.</p> <p>Cortar o lançamento também é o momento em que uma tag do git, um lançamento e essa entrada de changelog se encaixam ou começam a sair de sincronia; <a href="https://changeloop.dev/blog/pt-br/git-tags-releases-changelog/">tags do git, lançamentos e o seu changelog</a> cobre como manter os três sincronizados.</p> <h2>Três armadilhas</h2> <p><strong>Squash merges comem os footers.</strong> Se sua plataforma esmaga com o título da PR como mensagem, o footer <code>BREAKING CHANGE:</code> de um commit dentro daquela branch desaparece, e sua ferramenta para de ver a mudança que quebra algo silenciosamente. Verifique o que seu template de squash realmente mantém.</p> <p><strong>Commits de revert produzem entradas fantasmas.</strong> Um <code>fix</code> que é revertido no dia seguinte gera uma entrada para algo que nunca foi lançado, a menos que a derivação reconcilie reverts. A maioria das ferramentas não faz isso.</p> <p><strong>O incremento de versão e o changelog saem de sincronia.</strong> Se a versão é calculada a partir de commits e o changelog é escrito manualmente depois, eles divergem em cerca de duas releases. Calcule ambos na mesma passagem ou aceite que um dos dois está errado.</p> <h2>Se você quer a parte mecânica sem um pipeline</h2> <p>Nosso <a href="https://changeloop.dev/changelog-generator">gerador de changelog</a> faz a etapa de derivação no navegador: cole commits, receba entradas agrupadas e tipadas. É deliberadamente determinístico e inteiramente do lado do cliente, então os commits que você cola nunca saem da sua máquina, o que importa quando as mensagens vêm de um repositório privado. Faz a metade de coleta honestamente e não tenta a camada dois, porque a camada dois é um julgamento e uma ferramenta que a finge produz exatamente o changelog contra o qual este artigo argumenta.</p> <p>Para a versão de pipeline, <a href="https://changeloop.dev/changelog-tools">ferramentas de changelog</a> cobre o que existe.</p> <h2>O resumo</h2> <p>Conventional commits respondem "que tipo de mudança é esta" de forma confiável e barata. Não respondem "o que devemos dizer às pessoas", e nenhuma quantidade de ferramentas em cima da mensagem de commit vai fazer isso, porque a informação nunca esteve na mensagem de commit. Reserve um orçamento para a reescrita.</p> <h2>FAQ</h2> <p><strong>Conventional commits geram um changelog automaticamente?</strong> Eles geram um rascunho automaticamente: entradas tipadas, com scope, linkadas. A formulação para uma cliente, o agrupamento e a decisão do que deixar de fora ainda precisam de uma pessoa, e um pipeline que pula essa etapa publica mensagens de commit.</p> <p><strong>Quais tipos de conventional commit aparecem em um changelog?</strong> <code>feat</code> e <code>fix</code> sempre, como Added e Fixed. <code>perf</code> geralmente, como Changed. <code>chore</code>, <code>docs</code>, <code>refactor</code>, <code>test</code>, <code>build</code> e <code>ci</code> são internos por padrão e só aparecem se uma pessoa promover um.</p> <p><strong>Como conventional commits marcam uma mudança que quebra algo?</strong> Um <code>!</code> depois do tipo ou scope (<code>feat(api)!: ...</code>), ou um footer <code>BREAKING CHANGE:</code> no corpo do commit. Ambos se perdem se um squash merge mantiver só o título da PR.</p> <p><strong>Você precisa de conventional commits para automatizar um changelog?</strong> Não. Labels de PR, templates de PR e links de issue carregam os mesmos metadados para equipes que fazem merge por pull request. Conventional commits são a opção mais barata quando a unidade de mudança é o commit.</p> </article> <article> <h1>Como escrever release notes que as pessoas realmente leem</h1> <p>Fri, 28 Aug 2026 00:00:00 GMT</p> <p>Para escrever release notes que as pessoas leem, responda uma pergunta por entrada: o que o leitor pode fazer agora que antes não podia, e o que ele precisa fazer a respeito. Coloque qualquer coisa com prazo em primeiro lugar, nomeie quem é afetado, diga "nenhuma ação necessária" quando for verdade, e pule releases que não têm nada a dizer. Tudo mais nesta página é essa regra aplicada.</p> <blockquote> <p>Correções de bugs e melhorias de desempenho.</p> </blockquote> <p>Todo produto já publicou isso uma vez. A causa raramente é preguiça: isso é o que se obtém quando release notes são escritas de dentro, por alguém que passou duas semanas no diff e não consegue mais ver quais partes importariam para um estranho. Um tom melhor não vai resolver isso; responder à pergunta, sim.</p> <h2>O que release notes deveriam incluir?</h2> <p>Release notes deveriam incluir, para cada mudança que merece menção: o que o leitor pode fazer agora, quem é afetado, o que ele deve fazer a respeito (incluindo "nada"), e quando qualquer coisa com prazo entra em vigor. Não deveriam incluir números de tickets internos, nomes de componentes que só a equipe usa, ou um número de versão como único título.</p> <table> <thead> <tr> <th>Incluir</th> <th>Deixar de fora</th> </tr> </thead> <tbody><tr> <td>O resultado, nos termos do leitor</td> <td>A implementação, nos termos da equipe</td> </tr> <tr> <td>Quem é afetado, por plano, cargo ou versão de API</td> <td>"Alguns usuários"</td> </tr> <tr> <td>A ação necessária, ou "nenhuma ação necessária"</td> <td>Silêncio, que o leitor preenche com o pior cenário</td> </tr> <tr> <td>Uma data para qualquer coisa com prazo</td> <td>Um número de versão no lugar de uma data</td> </tr> <tr> <td>Um link para a doc que explica</td> <td>Um link para o pull request</td> </tr> <tr> <td>Bugs que as pessoas relataram, e o limite que foi elevado</td> <td>Ids de tickets internos</td> </tr> <tr> <td>A seção chata, uma linha cada, no final</td> <td>A seção chata misturada com as novidades</td> </tr> </tbody></table> <p>A separação entre uma release note e uma <a href="https://changeloop.dev/blog/pt-br/changelog-vs-release-notes/">entrada de changelog</a> é o que torna essa lista possível: o changelog guarda tudo, então as notas podem deixar coisas de fora. Exemplos comentados de cada tipo de entrada estão reunidos em <a href="https://changeloop.dev/blog/pt-br/release-notes-examples/">exemplos de release notes</a>.</p> <h2>A pergunta que cada entrada responde</h2> <p><strong>O que o leitor pode fazer agora que antes não podia, e o que ele precisa fazer a respeito?</strong></p> <p>Se uma entrada não consegue responder isso, ela pertence ao changelog e não às release notes. As duas metades importam. A primeira metade é o valor. A segunda metade é a que as equipes esquecem, e é a que gera tickets de suporte quando falta.</p> <p>Dois exemplos da segunda metade fazendo trabalho de verdade:</p> <ul> <li>"Webhooks existentes continuam funcionando até 1º de novembro. Depois dessa data, payloads sem assinatura serão rejeitados."</li> <li>"Nenhuma ação necessária. Exports existentes são recodificados automaticamente na próxima vez que você os abrir."</li> </ul> <p>O segundo diz "nenhuma ação necessária" explicitamente. Essa frase vale a pena escrever toda vez, porque um leitor que não a encontra assume o pior.</p> <h2>Como release notes deveriam ser ordenadas?</h2> <p>Ordene-as por consequência para o leitor, nunca pela parte do sistema que mudou. Agrupar por API, painel, mobile e infraestrutura é o organograma de vocês, não o problema do leitor.</p> <ol> <li><strong>Mudanças que quebram algo e qualquer coisa com prazo.</strong> Sempre em primeiro, mesmo que seja pequeno. Se um leitor para de ler depois de uma linha, essa é a linha que ele precisava ter lido. Se o prazo é um sunset, a entrada deveria soar como um <a href="https://changeloop.dev/blog/pt-br/api-deprecation/">aviso de depreciação</a>.</li> <li><strong>O que é novo e que eles vão querer.</strong> Um por parágrafo, com o resultado na primeira frase.</li> <li><strong>O que melhorou.</strong> Bugs que foram relatados, limites que foram elevados, coisas que estavam lentas.</li> <li><strong>Tudo mais, como lista.</strong> Atualizações de dependências, refatorações internas, texto menor. Uma linha cada. Ninguém lê essa seção, e ainda assim ela precisa estar lá, porque quem a procura realmente precisa dela.</li> </ol> <h2>A reescrita</h2> <p>Antes:</p> <blockquote> <p><strong>v4.2.0</strong> Corrigido um problema em que o endpoint <code>POST /exports</code> retornava 500 intermitentemente sob carga. Refatorado o worker de export. Atualizado <code>node-pg</code> para 8.11. Melhorado o tratamento de erros no serializador CSV.</p> </blockquote> <p>Depois:</p> <blockquote> <p><strong>Exports não falham mais em contas grandes.</strong> Contas com mais de aproximadamente 50.000 linhas podiam receber um 500 ao iniciar um export, mais frequentemente no fim do mês. Isso foi corrigido, e exports de qualquer tamanho agora tentam novamente sozinhos em vez de falhar. Nenhuma ação necessária, e qualquer export que falhou na última semana pode simplesmente ser executado novamente.</p> <p>Também na 4.2.0: <code>node-pg</code> 8.11, erros mais claros no serializador CSV.</p> </blockquote> <p>Mesma release. A segunda nomeia a conta afetada, o momento em que foi pior, o que mudou, e o que fazer. A atualização de dependência não desapareceu, só deixou de ser o título. O artigo <a href="https://changeloop.dev/blog/pt-br/release-notes-best-practices/">melhores práticas de release notes</a> tem o resto das regras que essa reescrita segue, cada uma com o custo de pulá-la.</p> <h2>Coisas que vale a pena eliminar</h2> <ul> <li><strong>"Estamos animados em anunciar."</strong> O leitor ainda não está animado. Conquiste isso na próxima frase.</li> <li><strong>Números de tickets internos.</strong> <code>PROJ-4471</code> não significa nada fora do tracker de vocês. Se a entrada precisa de uma referência, linke a página de docs.</li> <li><strong>Nomes de componentes que só a equipe de vocês usa.</strong> Se vocês renomearam o "pipeline de ingestão", digam "importações".</li> <li><strong>Um número de versão como único título.</strong> <code>v4.2.0</code> é um rótulo de arquivamento, não um resumo.</li> <li><strong>Screenshots de uma página de configurações que ninguém jamais visitou.</strong> Mostre o que mudou, em uso.</li> </ul> <h2>Com que frequência release notes deveriam ser publicadas?</h2> <p>Publique quando algo aconteceu, não em um cronograma. Notas que chegam a cada release ensinam todo mundo a ignorá-las. Notas que chegam quando algo aconteceu são abertas. Está tudo bem, e geralmente é correto, lançar uma release sem nenhuma nota e deixar suas entradas rolarem para o próximo conjunto que tenha um título que valha a pena ler.</p> <p>O changelog continua registrando tudo. Essa é a divisão de trabalho: o changelog é completo, as notas são seletivas. Se vocês mantiverem o changelog estruturado ao longo do caminho, escrever as notas se torna seleção e reescrita em vez de arqueologia.</p> <p>O <a href="https://changeloop.dev/release-notes-template">template de release notes</a> é a forma que usamos para a etapa de seleção, e <a href="https://changeloop.dev/changelog-examples">exemplos de changelog</a> reúne entradas de equipes cujo changelog é bom o suficiente para derivar notas dele.</p> <p>Tudo isso assume uma página que você controla totalmente, sem limite de tamanho e com links que funcionam. <a href="https://changeloop.dev/blog/pt-br/mobile-app-release-notes/">Release notes para apps mobile</a> cobre o que muda quando a superfície é uma listagem de App Store ou Play Store. <a href="https://changeloop.dev/blog/pt-br/emergency-release-notes/">Release notes de emergência</a> cobre a outra exceção: o que muda quando não sobra tempo nenhum para seguir o processo normal de escrita.</p> <h2>Um teste antes de publicar</h2> <p>Leia as notas como alguém que esteve de férias por duas semanas e tem 40 segundos. Se, nesse tempo, essa pessoa não conseguir dizer se algo é exigido dela, as notas não estão prontas, por mais precisas que sejam.</p> <h2>FAQ</h2> <p><strong>Quanto tempo release notes deveriam ter?</strong> O tempo que as mudanças com consequências exigirem, e nem uma linha a mais. Uma release com uma mudança que quebra algo e duas melhorias são três parágrafos. Encher uma release tranquila para parecer substancial é como os leitores aprendem a pular as notas.</p> <p><strong>Quem deveria escrever release notes?</strong> A pessoa que entende a mudança, editada por alguém que não entende. A engenheira sabe o que mudou; a editora sabe o que um estranho vai entender errado. Escrever a entrada no momento do merge, enquanto a engenheira ainda se lembra, é a prática que torna isso barato.</p> <p><strong>Release notes deveriam incluir correções de bugs?</strong> Sim, as que alguém relatou ou sofreu. Declare o sintoma que o leitor viu, não a causa. "Exports com mais de 50.000 linhas falhavam" é uma correção que um leitor reconhece; "corrigida uma race condition no worker de export" é uma mensagem de commit.</p> <p><strong>Qual é a diferença entre release notes e um changelog?</strong> O changelog é o registro completo e contínuo; as release notes são a mensagem selecionada sobre uma release, escrita para pessoas que ainda não decidiram se isso as interessa. A resposta mais longa está em <a href="https://changeloop.dev/blog/pt-br/changelog-vs-release-notes/">changelog vs release notes</a>.</p> </article> <article> <h1>Keep a Changelog, de fato implementado</h1> <p>Fri, 28 Aug 2026 00:00:00 GMT</p> <p>Keep a Changelog é uma convenção de uma página para um <code>CHANGELOG.md</code>: versão mais recente primeiro, uma seção por versão com um número e uma data ISO, entradas agrupadas sob seis tipos (Added, Changed, Deprecated, Removed, Fixed, Security), e uma seção Unreleased no topo para entradas entre releases. A maioria das equipes que a citam implementa cerca de dois terços dela, e o terço que deixam de lado é o terço que protege seus usuários.</p> <p>Olivier Lacan publicou o <a href="https://keepachangelog.com/">Keep a Changelog</a> em 2014 com uma frase que envelheceu melhor que a maioria da prosa de software: <em>don't let your friends dump git logs into changelogs</em>. Dez anos depois, é a coisa mais próxima de um padrão que este canto do software tem. Vale a pena ler a fonte em vez de um resumo; este texto trata das partes que são deixadas de lado.</p> <h2>O que o Keep a Changelog pede?</h2> <p>Um <code>CHANGELOG.md</code> na raiz do repo, mais recente primeiro, com uma seção por versão. Cada versão carrega um número e uma data ISO, e agrupa suas entradas sob seis tipos:</p> <table> <thead> <tr> <th>Tipo</th> <th>Para</th> <th>O que custa deixar de fora</th> </tr> </thead> <tbody><tr> <td>Added</td> <td>Novos recursos</td> <td>Nada; ninguém deixa esse de fora</td> </tr> <tr> <td>Changed</td> <td>Mudanças em comportamento existente</td> <td>Leitores descobrem uma mudança de comportamento por um erro</td> </tr> <tr> <td>Deprecated</td> <td>Recursos prestes a serem removidos</td> <td>Uma remoção vira um incidente em vez de um evento planejado</td> </tr> <tr> <td>Removed</td> <td>Recursos removidos nesta release</td> <td>Ninguém distingue uma remoção de um bug</td> </tr> <tr> <td>Fixed</td> <td>Correções de bugs</td> <td>Nada; ninguém deixa esse de fora também</td> </tr> <tr> <td>Security</td> <td>Vulnerabilidades</td> <td>A única leitora que procurava não encontra</td> </tr> </tbody></table> <p>Mais uma seção <code>Unreleased</code> no topo, para que haja um lugar para colocar uma entrada no momento em que ela é mergeada, e para que qualquer um possa ver o que está por vir.</p> <p>Isso é quase tudo. O resto é a justificativa: entradas são para humanos, uma entrada por mudança, e o arquivo é um documento em vez de um log.</p> <h2>Quais partes do Keep a Changelog são deixadas de lado?</h2> <p>A seção Unreleased, depois quatro dos seis tipos, Security entre eles, nessa ordem.</p> <p><strong><code>Unreleased</code> desaparece primeiro.</strong> É a seção sem prazo, então é a que para de ser mantida primeiro, e quando some as entradas passam a ser escritas no momento da release a partir do histórico de commits. Isso é precisamente o dump de git log contra o qual a especificação avisa logo no início, alcançado gradualmente. <a href="https://changeloop.dev/blog/pt-br/changelog-automation/">Automação de changelog</a> trata majoritariamente de manter essa seção viva sem que ninguém precise se lembrar.</p> <p><strong>Os seis tipos colapsam em dois.</strong> A maioria dos changelogs reais acaba com Added e Fixed, porque Changed e Deprecated exigem um julgamento sobre no que alguém confiava. Esse julgamento é a parte valiosa. Deprecated em particular é o único tipo que é uma promessa sobre o futuro, e deixá-lo de fora é como uma remoção vira um incidente; a mecânica de manter essa promessa está em <a href="https://changeloop.dev/blog/pt-br/api-deprecation/">como depreciar uma API</a>.</p> <p><strong>Security deixa de ser separado.</strong> Uma correção de segurança arquivada sob Fixed é invisível para a única leitora que estava procurando por ela. Mantenha-a distinta mesmo quando a correção for trivial, e especialmente quando você preferir não chamar atenção para ela.</p> <h2>O que a especificação não responde?</h2> <p>É um formato de arquivo. Não diz nada sobre as perguntas que você encontra imediatamente após adotá-la:</p> <ul> <li><strong>Como alguém descobre?</strong> Um arquivo em um repo alcança colaboradores. Não alcança uma cliente que nunca abriu o GitHub.</li> <li><strong>E produtos sem versões?</strong> Um serviço implantado continuamente não tem uma v4.2.0 para agrupar. A maioria das equipes substitui isso por datas, o que funciona, e a especificação nem abençoa nem proíbe.</li> <li><strong>Quem escreve a entrada?</strong> A especificação assume que um humano faz isso. Não diz quando.</li> <li><strong>E múltiplos públicos?</strong> Um arquivo serve desenvolvedores. Não serve o mesmo conteúdo para uma administradora não técnica, e reformatá-lo manualmente para ela é onde a duplicação começa. <a href="https://changeloop.dev/blog/pt-br/changelog-vs-release-notes/">Changelog vs release notes</a> é a divisão que a especificação deixa para vocês fazerem sozinhos.</li> </ul> <p><a href="https://common-changelog.org/">Common Changelog</a>, um fork mais rígido da ideia, aperta parte disso: proíbe certas formulações de entrada, exige um link para a mudança, e tem uma opinião clara sobre quem é o leitor. Vale a pena ler se as partes soltas do Keep a Changelog são o que sua equipe fica discutindo.</p> <h2>Dá para automatizar o Keep a Changelog sem despejar git logs?</h2> <p>Sim: derive o rascunho de commits estruturados, coloque-o em Unreleased com o tipo pré-preenchido, e exija que um humano edite a formulação antes que uma release seja cortada. O aviso da especificação é sobre a saída, não sobre a ferramenta. Derivar um rascunho de commits está bem. Publicar esse rascunho sem edição é a que ela se opõe.</p> <p>A máquina cuida de coleta e formatação, no que ela é boa. O humano cuida de seleção e formulação, no que ela não é. <a href="https://changeloop.dev/blog/pt-br/conventional-commits-changelog/">Conventional commits</a> cobre a divisão em duas camadas da qual isso depende, e quais tipos de commit mapeiam para quais das seis categorias acima. Nosso resumo <a href="https://changeloop.dev/changelog-tools">ferramentas de changelog</a> cobre o que existe para a metade de coleta.</p> <h2>Onde o Keep a Changelog para de ser suficiente?</h2> <p>Para na distribuição. Keep a Changelog é uma boa resposta para "como esse arquivo deveria parecer". Não é uma resposta para "como nossos usuários descobrem o que mudou", porque um arquivo Markdown em um repo é uma estratégia de distribuição que só funciona se seus usuários forem colaboradores.</p> <p>Esse é o obstáculo que a maioria das equipes encontra em segundo lugar: o arquivo está bem, e ninguém fora da equipe o lê. Resolver isso significa que as entradas precisam virar dados que podem ser renderizados em outro lugar, o que é um problema diferente de formatar um arquivo, e o motivo pelo qual <a href="https://changeloop.dev/changelog-examples">exemplos de changelog</a> reúne páginas públicas de changelog em vez de arquivos de repositório. Como transformar essas entradas em algo que as pessoas voltam a acompanhar é coberto em <a href="https://changeloop.dev/blog/pt-br/changelog-page/">como construir uma página de changelog</a>.</p> <p>Adote a especificação mesmo assim. Custa uma tarde, torna o segundo problema tratável, e ainda é a melhor página já escrita sobre o assunto.</p> <h2>FAQ</h2> <p><strong>Keep a Changelog é um padrão?</strong> É uma convenção amplamente adotada, não a especificação de um órgão de padronização. Ferramentas (scripts de release, linters, parsers) assumem sua forma com frequência suficiente para que segui-la compre compatibilidade.</p> <p><strong>O que entra na seção Unreleased?</strong> Toda entrada para uma mudança que foi mergeada mas ainda não foi lançada em uma release numerada. Quando uma release é cortada, a seção é renomeada para a versão e data, e uma nova seção Unreleased vazia vai acima dela.</p> <p><strong>Um changelog deveria usar versionamento semântico?</strong> Keep a Changelog recomenda e não exige. Bibliotecas e APIs se beneficiam; um serviço implantado continuamente geralmente substitui por datas, o que o formato acomoda.</p> <p><strong>Correções de segurança deveriam estar no changelog antes de serem públicas?</strong> Adicione a entrada quando a correção for lançada, com detalhe suficiente para que uma operadora possa agir e não mais. Atrasar a entrada até uma data de divulgação coordenada é normal; omiti-la não é.</p> </article> <article> <h1>Melhores práticas de release notes que valem a pena</h1> <p>Fri, 28 Aug 2026 00:00:00 GMT</p> <p>As melhores práticas de release notes que importam são as que têm uma consequência anexada: escreva a entrada no momento do merge, nomeie quem é afetado, declare a ação necessária mesmo quando é nenhuma, dê uma data às mudanças que quebram algo, mantenha uma entrada permanente por mudança, agrupe por resultado, e mantenha a seção chata. Cada uma muda o que o leitor faz. A maioria dos outros conselhos sobre esse assunto muda a aparência das notas.</p> <p>Pesquise por melhores práticas de release notes e você recebe conselho de estilo: seja claro, seja conciso, use linguagem simples, adicione screenshots. Nada disso está errado e nada disso muda nada, porque nenhuma equipe jamais se sentou com a intenção de ser confusa. As práticas abaixo vêm acompanhadas do que custa pulá-las, porque uma prática sem um modo de falha anexado é só uma preferência.</p> <table> <thead> <tr> <th>Prática</th> <th>O que custa pular</th> </tr> </thead> <tbody><tr> <td>Escrever a entrada no merge, não na release</td> <td>Entradas reconstruídas depois dizem "várias melhorias"</td> </tr> <tr> <td>Nomear quem é afetado</td> <td>Todo leitor decide que não se aplica a ele</td> </tr> <tr> <td>Declarar a ação necessária, incluindo "nenhuma"</td> <td>Quarenta tickets de suporte idênticos, e leitores que assumem o pior</td> </tr> <tr> <td>Datar mudanças que quebram algo, não versioná-las</td> <td>O prazo é descoberto depois de passar</td> </tr> <tr> <td>Uma entrada permanente e linkável por mudança</td> <td>Ninguém consegue responder "quando isso mudou"</td> </tr> <tr> <td>Agrupar por resultado, não por sistema</td> <td>Leitores precisam da arquitetura de vocês para achar sua seção</td> </tr> <tr> <td>Manter a seção chata</td> <td>Segurança, compliance e quem debuga uma versão perdem sua fonte</td> </tr> </tbody></table> <h2>Quais são as melhores práticas para release notes?</h2> <p><strong>Escreva a entrada quando fizer o merge, não quando lançar.</strong> Custo de pular: a pessoa que reconstrói a release a partir do histórico de commits não é quem fez a mudança, e vai chutar a intenção. Entradas escritas duas semanas depois são as que dizem "várias melhorias".</p> <p><strong>Diga quem é afetado, pelo nome.</strong> "Equipes no plano Business", "qualquer um usando a API de export v1", "instalações self-hosted em Postgres 14". Custo de pular: todo leitor tem que descobrir se se aplica a ele, e a maioria vai decidir que não.</p> <p><strong>Declare a ação necessária, incluindo quando é nenhuma.</strong> Custo de pular: o suporte responde a mesma pergunta quarenta vezes, e os leitores que não perguntaram simplesmente assumem que algo é necessário e adiam.</p> <p><strong>Dê uma data às mudanças que quebram algo, não um número de versão.</strong> "Removido na v5" não significa nada para quem não sabe quando a v5 chega. "Deixa de funcionar em 1º de novembro" significa a mesma coisa para todos. Custo de pular: o prazo é descoberto depois de passar. O que conta como tal, e a checklist para lançá-la, estão em <a href="https://changeloop.dev/blog/pt-br/breaking-changes/">o que é uma mudança que quebra algo</a>.</p> <p><strong>Mantenha uma entrada permanente e linkável por mudança.</strong> Um e-mail não é um arquivo e uma mensagem no Slack não é uma referência. Custo de pular: ninguém consegue responder "quando isso mudou" seis meses depois, nem vocês. O e-mail ainda tem seu papel, coberto em <a href="https://changeloop.dev/blog/pt-br/product-update-email/">o template de e-mail de atualização de produto</a>; ele aponta para a entrada em vez de substituí-la.</p> <p><strong>Agrupe por resultado, não por sistema.</strong> Custo de pular: o leitor precisa ter a arquitetura de vocês na cabeça para saber qual seção importa para ele. A ordem que decorre disso está em <a href="https://changeloop.dev/blog/pt-br/how-to-write-release-notes/">como escrever release notes</a>.</p> <p><strong>Mantenha a seção chata.</strong> Atualizações de dependências e mudanças internas ficam, no final, uma linha cada. Custo de pular: a equipe de segurança, quem revisa compliance e quem debuga uma incompatibilidade de versão perdem sua única fonte. As entradas que mais erram nisso são as correções; <a href="https://changeloop.dev/blog/pt-br/bug-fix-release-notes/">release notes de correção de bugs</a> mostra como escrevê-las para que o leitor saiba se precisa agir.</p> <h2>Quais são as melhores práticas de changelog, e como diferem?</h2> <p>Um changelog é uma referência, então suas práticas são sobre completude e estrutura em vez de persuasão. As quatro que importam:</p> <ul> <li><strong>Um tipo de entrada fixo por linha.</strong> Added, Changed, Deprecated, Removed, Fixed, Security. Não é um estilo de casa, é um filtro: é o que permite pedir "só as mudanças que quebram algo". A convenção <a href="https://changeloop.dev/blog/pt-br/keep-a-changelog-implemented/">Keep a Changelog</a> é a fonte usual.</li> <li><strong>Uma seção não lançada.</strong> Onde as entradas vivem entre o merge e a release. Sua ausência é o motivo pelo qual as equipes escrevem entradas tarde.</li> <li><strong>Datas ISO.</strong> <code>2026-08-28</code>, não <code>28/08/26</code>, que significa dois dias diferentes dependendo do leitor.</li> <li><strong>Uma entrada por mudança, não por commit.</strong> Três commits corrigindo um bug são uma entrada.</li> </ul> <p>Os dois artefatos são comparados a fundo em <a href="https://changeloop.dev/blog/pt-br/changelog-vs-release-notes/">changelog vs release notes</a>; a versão curta é que as práticas do changelog protegem a completude e as das release notes protegem a atenção. <a href="https://changeloop.dev/blog/pt-br/private-release-notes-enterprise/">Release notes privadas para clientes enterprise</a> cobre uma versão disso que só aparece quando as clientes de vocês não estão mais todas no mesmo build: os mesmos objetivos de completude e atenção, mas calibrados por conta em vez de transmitidos a todas de uma vez.</p> <h2>Três que são puro culto da forma</h2> <p><strong>Emoji como tipos de entrada.</strong> Um foguete e uma chave inglesa não são uma taxonomia. Parecem organizados e não podem ser filtrados, ordenados, ou lidos de forma útil por um leitor de tela. Use palavras, e se quiser o emoji, coloque-o depois da palavra.</p> <p><strong>Números de versão semântica como títulos para um produto hospedado.</strong> Semver é uma promessa sobre compatibilidade de API. Para um produto SaaS onde ninguém escolhe sua versão, um número de versão no título é arquivamento interno disfarçado de notícia. Mantenha semver no changelog e fora do anúncio.</p> <p><strong>Publicar em um cronograma independentemente do conteúdo.</strong> Notas mensais sem nada dentro ensinam as pessoas que suas notas são ruído. Publique quando houver algo a dizer. O changelog cobre o resto.</p> <h2>A que é realmente difícil</h2> <p>Manter o changelog e o anúncio sincronizados, sem escrever tudo duas vezes.</p> <p>A maioria das equipes começa com uma única página, a divide quando os públicos divergem, e então deixa silenciosamente um dos dois apodrecer, geralmente o changelog, porque é o que não tem um prazo anexado. A saída é estrutural em vez de disciplinar: mantenha as entradas como dados com um tipo, uma data e um público, e trate ambas as superfícies como renderizações disso. Nosso resumo <a href="https://changeloop.dev/changelog-tools">ferramentas de changelog</a> cobre o que existe para isso, incluindo as ferramentas com as quais competimos, e a página <a href="https://changeloop.dev/beamer-alternative">alternativa ao Beamer</a> é a comparação honesta contra o widget de onde a maioria das equipes parte.</p> <p>O <a href="https://changeloop.dev/release-notes-template">template de release notes</a> é onde vive a etapa de seleção assim que as entradas existem.</p> <h2>Se você só adotar uma coisa</h2> <p>Escreva a entrada no momento do merge, em um formato fixo, com um tipo. Toda outra prática nesta página fica mais fácil assim que essa está no lugar, e nenhuma sobrevive sem ela.</p> <h2>FAQ</h2> <p><strong>Release notes deveriam ter screenshots?</strong> Só do que mudou, em uso. Um screenshot de uma página de configurações que ninguém jamais visitou adiciona scroll, não informação. Um texto que nomeia o resultado e o leitor afetado vence uma imagem que não mostra nenhum dos dois.</p> <p><strong>Como se escreve release notes para uma mudança que quebra algo?</strong> Primeiro a data, segundo os chamadores afetados, terceiro a ação necessária, quarto a migração. Nunca comece pelo número de versão. A forma completa, com uma entrada de exemplo, está em <a href="https://changeloop.dev/blog/pt-br/breaking-changes/">o que é uma mudança que quebra algo</a>.</p> <p><strong>Release notes deveriam ser escritas pela engenharia ou pelo marketing?</strong> Redigidas pelo engenheiro que fez a mudança, no momento do merge, e editadas por alguém que as lê como um estranho. Nenhum dos dois sozinho produz notas sobre as quais um cliente possa agir.</p> <p><strong>Qual é o formato ideal de release notes?</strong> Primeiro os itens com prazo, depois as novas capacidades, depois as melhorias, depois uma lista de uma linha cada para o resto. O <a href="https://changeloop.dev/release-notes-template">template de release notes</a> é esse formato como uma página para preencher.</p> </article> </main></body></html>