Changelog: o que é, com um exemplo de entrada

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.

O que é um changelog, exatamente?

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.

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. Keep a Changelog é 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.

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.

O que uma entrada de changelog realmente contém?

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ê.

## 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.

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.

Quem escreve um changelog, e quando?

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.

Onde um changelog deveria viver?

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.

Como ele difere das notas de versão?

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. Changelog versus notas de versão 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.

O que faz um changelog valer a pena ser lido?

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.

A disciplina de versionamento também importa. Semantic versioning e o seu changelog 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.

Como os changelogs são gerados?

De duas formas, e a maioria das configurações reais é uma mistura. A geração automatizada lê mensagens de commit, geralmente no formato Conventional Commits, e as transforma em entradas sem que ninguém toque no resultado; de conventional commits a changelog 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.

FAQ

Todo produto precisa de um changelog? 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.

O que é um changelog em termos de software? 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.

Um changelog pode ser gerado automaticamente a partir de commits? 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.

Um changelog é a mesma coisa que um histórico de versões? 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.

As afirmações técnicas deste artigo não foram revisadas de forma independente. Se algo estiver errado, avise a gente e vamos corrigir.

Relacionado na changeloop: Exemplos de changelog, Documentação para desenvolvedores