Gerador de Keep a Changelog

Keep a Changelog: um changelog feito para humanos

Keep a Changelog é uma convenção criada por Olivier Lacan em 2014 (mantida em github.com/olivierlacan/keep-a-changelog) que define como estruturar um arquivo CHANGELOG.md na raiz do projeto. O princípio é que changelog é escrito para humanos, não para máquinas: um log de commits cru não é um changelog. Cada versão tem sua própria seção, mudanças semelhantes ficam agrupadas e o release mais novo aparece no topo.

Um arquivo canônico começa com cabeçalho, descrição, uma seção ## [Unreleased] que acumula mudanças pendentes e depois as versões em ordem cronológica inversa. Cada versão agrupa entradas sob títulos fixos:

# Changelog

## [Unreleased]
### Added
- Novo webhook para eventos de assinatura.

## [1.2.0] - 2026-05-20
### Added
- Endpoint de importação em lote.
### Fixed
- Parser de data quebrava em leap seconds.
### Security
- Atualizado lodash para corrigir CVE-2026-1234.

[Unreleased]: https://github.com/acme/app/compare/1.2.0...HEAD
[1.2.0]: https://github.com/acme/app/compare/1.1.0...1.2.0

As seis categorias de mudança

• Added — novas funcionalidades.
• Changed — alterações em funcionalidade existente.
• Deprecated — recursos ainda funcionando, marcados para remoção.
• Removed — recursos removidos no release.
• Fixed — correções de bug.
• Security — vulnerabilidades e patches de CVE.

Por que um changelog cultivado ainda importa

Usuários decidem se atualizam lendo o changelog, não folheando git log. Um arquivo bem cuidado constrói confiança nos mantenedores e em contextos regulados (segurança, auditoria, compliance) o changelog costuma ser o registro oficial do que foi entregue e quando — sobretudo para CVEs e breaking changes. Os links de comparação no rodapé ([1.2.0]: .../compare/1.1.0...1.2.0) levam direto para o diff do git de qualquer release.

Cultivado vs auto-gerado

Duas culturas convivem. Ferramentas Conventional Changelog parseiam Conventional Commits e emitem o arquivo automaticamente — é rápido, mas o texto é tão bom quanto suas mensagens de commit. Keep a Changelog é escrito à mão e lê melhor, mas custa tempo editorial. Muitos projetos misturam: gerar um rascunho dos commits e revisar antes de tagear o release. CLIs como kacl, o parser npm keepachangelog e GitHub Actions conseguem fazer lint do arquivo em pull requests para que o formato nunca quebre.

Changelog vs git tags vs release notes

Git tags marcam versões em commits, mas não dizem nada sobre o conteúdo. Release notes são o markdown livre exibido na UI de releases do GitHub/GitLab, em geral marketing por release. O changelog é um arquivo versionado dentro do repo, com histórico, que complementa os dois: tags apontam para commits, release notes vendem o valor, e o changelog explica o diff em um lugar estável.

Perguntas frequentes

Preciso escrever uma entrada por commit? Não. Você escreve no momento do release. Durante o desenvolvimento, acumule sob ## [Unreleased] e mova para o título versionado no momento de tagear.

Posso gerar dos commits? Sim, se você seguir Conventional Commits, ferramentas como conventional-changelog ou git-cliff produzem saída compatível com Keep a Changelog. Revisar o rascunho antes de publicar ainda é recomendado.

Um item depreciado fica para sempre? Não. Quando o recurso é removido de fato, a entrada migra de Deprecated no release antigo para Removed no release que o tira.

Devo traduzir o changelog? A convenção é manter uma fonte única em inglês e linkar traduções a partir de um site de docs separado. Cópias divergentes de CHANGELOG.md por idioma se desincronizam rápido.