Como manter um CHANGELOG.md útil

Um changelog é escrito para pessoas. Veja a estrutura da especificação Keep a Changelog 1.1.0 e um modelo curto.

Como organizar um arquivo CHANGELOG.md?

Uma entrada por versão, a mais nova primeiro, com a data em ISO 8601 e as mudanças agrupadas em Adicionado, Modificado, Obsoleto, Removido, Corrigido e Segurança. Mantenha uma seção Unreleased no topo.

Para que serve um changelog

Um changelog é um arquivo, em geral CHANGELOG.md na raiz, que lista o que mudou em cada versão. A primeira ideia da especificação Keep a Changelog é que ele é escrito para pessoas, não para máquinas. Quem usa o seu projeto abre o arquivo para decidir se atualiza, e quem contribui o abre para ver o que já foi feito. Copiar o histórico de commits para o arquivo costuma não servir (é prática comum, não regra da especificação): os commits dizem o que o desenvolvedor fez; o changelog diz o que muda para quem usa.

Os princípios

A página lista os princípios que sustentam um bom changelog:

Cada versão tem a sua entrada.
Mudanças do mesmo tipo ficam agrupadas.
Versões e seções podem ser linkadas.
A versão mais nova aparece primeiro.
Cada versão mostra a data do lançamento, de preferência no formato ISO 8601 (2026-10-11).
O arquivo diz se o projeto segue o versionamento semântico.

Os tipos de mudança

A versão 1.1.0 da especificação, em português do Brasil, agrupa as mudanças em seis tipos:

Tipo	Para quê
Adicionado	funcionalidades novas
Modificado	mudanças em funcionalidades existentes
Obsoleto	funcionalidades que serão removidas em breve
Removido	funcionalidades removidas nesta versão
Corrigido	correções de defeitos
Segurança	vulnerabilidades corrigidas

A seção Unreleased

Mantenha no topo uma seção chamada Unreleased (não lançado) com o que já foi feito e ainda não saiu em versão. Quando você lançar, move o conteúdo dela para a seção da nova versão, com número e data. Assim você escreve a nota na hora da mudança, que é quando você mais lembra do motivo, e não na hora de lançar.

Changelog, commits e releases

Se o projeto usa Conventional Commits, os tipos feat e fix ajudam a montar o rascunho: cada feat vira uma linha em Adicionado e cada fix em Corrigido. Ainda assim, releia e reescreva em linguagem de quem usa. Uma mensagem como "refactor: extrai função" não precisa aparecer; "o comando list agora aceita --json" precisa.

Exemplo resolvido: um CHANGELOG.md pequeno

# Changelog

Todas as mudanças importantes deste projeto aparecem aqui.
O projeto segue o versionamento semântico (https://semver.org/lang/pt-BR/).

## [Unreleased]

### Adicionado
- Filtro por etiqueta no comando `list`.

## [1.4.3] - 2026-10-11

### Corrigido
- O comando `list` não trava mais quando o arquivo de tarefas está vazio.

## [1.4.2] - 2026-09-20

### Segurança
- Atualizada uma dependência com vulnerabilidade conhecida.

O texto deste exemplo é nosso, escrito para este guia. Ele segue as regras acima: versão mais nova no alto, data em ISO 8601, mudanças agrupadas por tipo, Unreleased no começo e a frase que diz que o projeto segue o SemVer.

Perguntas frequentes

Posso gerar o changelog a partir dos commits?

Pode usar os commits como rascunho, principalmente se o projeto segue o Conventional Commits, em que feat e fix indicam o tipo da mudança. Mesmo assim, releia e reescreva em linguagem de quem usa o projeto, porque o changelog é para pessoas, não para máquinas.

Para que serve a seção Unreleased?

Guarda as mudanças que já foram feitas e ainda não saíram em uma versão. No lançamento, o conteúdo passa para a seção da nova versão, com número e data. Assim você anota a mudança na hora em que lembra do motivo.

Qual formato de data usar?

A especificação Keep a Changelog recomenda ISO 8601, no formato ano-mês-dia, como 2026-10-11. Ele não depende do idioma e ordena corretamente quando listado.

Preciso seguir o versionamento semântico?

A especificação pede que o changelog diga se o projeto segue o SemVer, mas não obriga a seguir. Se você segue, o número de cada entrada mostra ao leitor o tamanho da mudança, e a ligação entre as duas fontes fica clara.

Fontes deste guia

Abertas em 11/10/2026. O texto é nosso, em português; as fontes ficam aqui com link, licença e o que foi lido.

Keep a Changelog 1.1.0 (pt-BR) (keepachangelog.com)
A página não mostra data · aberta em 11/10/2026 · reconferência: confirmada na abertura (11/10/2026) · licença do conteúdo: MIT
O que lemos: Os princípios (changelog é para pessoas, uma entrada por versão, tipos agrupados, mais novo primeiro, data em ISO 8601, dizer se segue SemVer), a seção Unreleased e os seis tipos de mudança.
Como usamos: Texto próprio em português; os fatos e os comandos vêm da página, sem copiar trechos. Link e data em cada uso.
Versionamento Semântico 2.0.0 (semver.org)
A página não mostra data · aberta em 11/10/2026 · reconferência: confirmada na abertura (11/10/2026) · licença do conteúdo: CC BY 3.0
O que lemos: As 11 regras da versão 2.0.0 (API pública, X.Y.Z, versão lançada não muda, 0.y.z, pré-lançamento com hífen, metadados com +, precedência) e o resumo MAJOR, MINOR e PATCH.
Como usamos: Resumo próprio das regras, em português, com o número da regra. O texto da especificação não é reproduzido.
Conventional Commits 1.0.0 (conventionalcommits.org)
A página não mostra data · aberta em 11/10/2026 · reconferência: confirmada na abertura (11/10/2026) · licença do conteúdo: CC BY 3.0
O que lemos: As 16 regras numeradas (tipo, escopo, ! , descrição, corpo, rodapés, BREAKING CHANGE), a ligação entre feat e fix e os números MINOR e PATCH do SemVer, a lista de tipos recomendada pelo @commitlint/config-conventional e os exemplos. A versão exibida é a 1.0.0; a página não marca nenhuma versão mais nova.
Como usamos: As regras são resumidas em português e citadas por número. Os trechos em inglês são curtos, de regras, com a fonte ao lado.

Informação geral, não é aconselhamento jurídico. Quando um guia cita uma licença de conteúdo, ela vale para a página citada, não para este site.

Continue pelos guias

Os geradores, o passo a passo e os guias ficam a um clique.