O que Gerador de Changelog faz?
Gera changelogs legíveis automaticamente a partir do histórico git. Segue o formato Keep a Changelog, refina mensagens de commit para linguagem amigável e, opcionalmente, cria GitHub Releases.
Resolução de Entrada
A entrada principal é um intervalo de refs git. Resolva o argumento (se fornecido):
- Contém
...ou..-> intervalo de refs git (ex.:v1.0.0...v1.1.0) - Corresponde a uma única tag/ref -> daquela ref até HEAD
- Corresponde a uma URL do GitHub ou padrão
#\d+-> PR (extrai mudanças apenas daquele PR). Para entrada de PR único: leia o diff e a descrição do PR, categorize as mudanças, use o título do PR como entrada. Pule o cabeçalho de versão. Pergunte ao usuário se deseja anexar essas entradas a uma versão existente do changelog ou criar uma nova. - Nenhum argumento -> pergunte: "Qual intervalo o changelog deve cobrir? Você pode fornecer um intervalo de refs git (ex.: v1.0.0...v1.1.0), uma tag (mudanças desde aquela tag) ou um número de PR."
Fluxo do Processo
digraph changelog {
rankdir=TB;
"Resolver entrada" [shape=box];
"Fase 1: Coletar" [shape=box];
"Fase 2: Categorizar" [shape=box];
"Fase 3: Refinar" [shape=box];
"Fase 4: Revisar" [shape=box];
"Aprovado?" [shape=diamond];
"Fase 5: Saída" [shape=box];
"Resolver entrada" -> "Fase 1: Coletar";
"Fase 1: Coletar" -> "Fase 2: Categorizar";
"Fase 2: Categorizar" -> "Fase 3: Refinar";
"Fase 3: Refinar" -> "Fase 4: Revisar";
"Fase 4: Revisar" -> "Aprovado?";
"Aprovado?" -> "Fase 3: Refinar" [label="revisões"];
"Aprovado?" -> "Fase 5: Saída" [label="sim"];
}
NÃO pule fases. Faça perguntas em um ritmo natural. Se o usuário responder várias de uma vez, aceite respostas agrupadas e avance.
Se o usuário disser "apenas escolha os padrões" ou similar, escolha padrões razoáveis, informe o que escolheu e peça uma única confirmação.
Fase 1: Coletar
Passo 1 - Coletar commits e PRs
Execute git log entre as duas refs para coletar todos os commits. Se o repositório usar PRs, também verifique PRs mesclados no intervalo usando gh pr list --state merged.
Para cada commit/PR, extraia:
- Mensagem do commit (assunto + corpo)
- Arquivos alterados (para determinar o escopo)
- Título e descrição do PR (se disponível)
- Qualquer prefixo de tipo de commit convencional (feat, fix, chore, etc.)
Passo 2 - Ler contexto mais amplo do produto
Leia, se existirem: README, package.json (ou equivalente). Objetivo: entender o que é o produto para escrever descrições amigáveis.
Se nada for encontrado, pergunte: "Você pode descrever brevemente o produto? Preciso de contexto para escrever entradas de changelog amigáveis."
Passo 3 - Detectar formato existente
Verifique se o repositório tem um CHANGELOG.md existente. Se tiver:
- Detectar o formato (Keep a Changelog, personalizado, etc.)
- Detectar se usa rótulos com emojis (ex.: emojis para Novo, Correção de bug, Quebra) ou categorias em texto simples
- Corresponder ao estilo existente
Se não houver changelog existente:
- Padrão para formato Keep a Changelog
- Pergunte: "Nenhum changelog existente encontrado. Você prefere rótulos com emojis (ex.: para Novo, Correção de bug) ou categorias em texto simples (Adicionado, Corrigido, etc.)?"
Fase 2: Categorizar
Classifique todas as mudanças nas categorias Keep a Changelog. Mudanças de Quebra recebem uma seção dedicada no topo:
- Mudanças de Quebra - qualquer mudança que quebre comportamentos ou APIs existentes, ou que exija ação do usuário para atualizar. Inclua notas de migração para cada uma. Detecte a partir de
feat!:,fix!:, rodapésBREAKING CHANGE:ou APIs removidas/renomeadas no diff. - Adicionado - novas funcionalidades
- Alterado - mudanças em funcionalidades existentes
- Obsoleto - funcionalidades que serão removidas
- Removido - funcionalidades que foram removidas
- Corrigido - correções de bugs
- Segurança - correções de vulnerabilidades
Regras de categorização:
- Se os commits seguem commits convencionais (
feat:,fix:, etc.), use o tipo para categorizar - Se não, analise o diff e a mensagem do commit para determinar a categoria
- Pule mudanças apenas internas (refatorações, adições de testes, mudanças de CI, bumps de dependência) a menos que afetem o comportamento visível ao usuário
- Quando houver dúvida se uma mudança é visível ao usuário, inclua-a e deixe o usuário removê-la na revisão
- Para intervalos com 50+ commits, agrupe mudanças relacionadas em entradas de nível superior (ex.: em vez de listar 12 correções individuais de API, escreva "Melhorias no tratamento de erros da API em vários endpoints"). Apresente a versão agrupada e deixe o usuário expandir qualquer grupo se quiser detalhes.
Apresente a lista categorizada:
"Aqui está o que encontrei neste intervalo:"
Adicionado (3)
- Funcionalidade A
- Funcionalidade B
- Funcionalidade C
Corrigido (2)
- Correção de bug A
- Correção de bug B
"Algo para adicionar, remover ou recategorizar?"
NÃO prossiga até que o usuário confirme.
Fase 3: Refinar
Reescreva cada entrada em linguagem amigável:
- Comece com o benefício para o usuário, não com o detalhe de implementação
- "Relatórios agora carregam 3x mais rápido" não "Plano de execução de consulta SQL otimizado para o módulo de relatórios"
- "Agora você pode exportar relatórios para PDF" não "Funcionalidade de exportação para PDF adicionada ao serviço de relatórios"
- Mantenha cada entrada em uma linha (no máximo duas para mudanças complexas)
- Inclua referências a PRs/issues quando disponíveis (ex.:
(#123))
Cabeçalho de versão
Formato: ## [versão] - AAAA-MM-DD
Se o limite superior do intervalo for uma tag de versão (ex.: v1.2.0), use essa versão. Se o limite superior for HEAD ou um nome de branch, pergunte: "Qual número de versão este changelog deve usar?"
Use a data do commit mais recente no intervalo, no formato ISO (AAAA-MM-DD).
Apêndice técnico
Após gerar o changelog amigável, pergunte:
"Quer que eu também gere um apêndice técnico com detalhes de implementação? (útil para documentação voltada a desenvolvedores)"
Se sim, gere uma seção mais detalhada com especificações técnicas, guias de migração de mudanças de quebra e mudanças de API.
Regras de escrita
- Nunca use travessões no conteúdo gerado. Sem caracteres "---". Use vírgulas, dois pontos, pontos ou parênteses em vez disso.
- Linguagem amigável por padrão (sem jargão, sem nomes internos de funcionalidades)
- Uma linha por entrada, no máximo duas para mudanças complexas
- Tempo verbal consistente (passado: "Adicionado", "Corrigido", "Removido")
- Inclua referências a PRs/issues quando disponíveis
Fase 4: Revisar
Apresente a entrada completa do changelog:
"Aqui está o changelog:"
## [1.2.0] - 2026-04-11 ### Adicionado - Agora você pode exportar relatórios para PDF (#123) ### Corrigido - Dashboard não pisca mais ao carregar a página (#456)"Quer alguma alteração?"
Aguarde aprovação. Prossiga para a saída somente após o usuário confirmar.
Fase 5: Saída
CHANGELOG.md
Detecte o CHANGELOG.md existente na raiz do repositório. Se encontrado, leia o arquivo inteiro, identifique o ponto de inserção (antes da primeira linha ## [), apresente o ponto de inserção proposto ao usuário e confirme antes de escrever. Se não encontrado, crie um com um cabeçalho padrão:
# Changelog
Todas as mudanças notáveis neste projeto serão documentadas neste arquivo.
O formato é baseado no [Keep a Changelog](https://keepachangelog.com/).
Sempre confirme antes de escrever:
"Vou pré-anexar isso ao
CHANGELOG.md. Pode prosseguir?"
GitHub Release
Após salvar o changelog, pergunte:
"Quer que eu também crie uma GitHub Release com este changelog?"
Se sim, use gh release create <tag> --notes "<conteúdo do changelog>" para criar a release. Se gh não estiver disponível, informe o usuário e pule.
Tratamento de Erros
ghnão disponível -> informe o usuário, pule enriquecimento de PR e GitHub Release, dependa apenas do git log- Ref/tag inválida -> peça ao usuário para verificar
- Nenhum commit no intervalo -> informe o usuário, peça para verificar o intervalo
- Nenhum contexto do produto -> peça ao usuário para descrever o produto
- Commits não convencionais -> recorra à análise de diff para categorização
O que esta habilidade NÃO faz
- Gerenciar estratégia de versionamento (decisões de versionamento semântico são do usuário)
- Publicar em registros de pacotes
- Gerar posts de blog ou newsletters (use
/blog-postou/newsletter) - Lidar com estratégias de branching ou workflows de release