Notas de Versão (release-notes)
Transforma o histórico bruto do Git em notas de versão que um ser humano realmente gostaria de ler.
O que ela faz
- Faz diff de commits entre duas refs (tags, branches ou
HEAD) - Agrupa mudanças por tipo: funcionalidades, correções, mudanças que quebram compatibilidade, tarefas
- Detecta mudanças que quebram compatibilidade a partir de marcadores
!de commit convencional e rodapésBREAKING CHANGE: - Redige uma seção de destaques (as 3 a 5 mudanças que os usuários realmente se importam)
- Gera Markdown pronto para release do GitHub
Uso
# Notas para a próxima versão (última tag -> HEAD)
git log $(git describe --tags --abbrev=0)..HEAD --oneline
# Entre duas tags
git log v1.2.0..v1.3.0 --pretty=format:'%h %s %b'
Depois peça ao agente: "redija as notas de versão para v1.3.0 a partir destes commits."
Ou com a CLI do GitHub, diretamente em um rascunho de release:
# Crie a tag, depois redija as notas de versão a partir do diff
git tag v1.3.0 && git push origin v1.3.0
gh release create v1.3.0 --generate-notes --draft
# depois refine as notas geradas com esta skill
Processo
1. Coletar os commits
git log <tag-anterior>..<nova-tag> --pretty=format:'%h|%s|%b|%an' --no-merges
Inclua commits de merge separadamente se o repositório usa fluxo baseado em merge — o título do merge geralmente resume o PR melhor que commits individuais.
2. Classificar cada commit
| Prefixo / sinal | Seção |
|---|---|
feat, feat! | Funcionalidades |
fix | Correções de bugs |
! ou BREAKING CHANGE: | ⚠️ Mudanças que quebram compatibilidade (também listadas na própria seção) |
perf | Performance |
docs, chore, ci, refactor, test | Agrupado em "Outros" ou omitido |
Commits sem prefixos convencionais: classifique pelo conteúdo da mensagem. Em caso de dúvida, coloque em "Outras mudanças" em vez de descartá-lo silenciosamente.
3. Redigir os destaques
Escolha as 3 a 5 mudanças que mais importam para os usuários do software:
- Novas capacidades que eles notarão
- Mudanças que quebram compatibilidade que eles precisam agir
- Correções para problemas amplamente relatados
Escreva cada uma como uma frase simples. Sem adjetivos de marketing.
4. Escrever as notas
## v1.3.0
**Destaques**
- ...
- ...
### ⚠️ Mudanças que quebram compatibilidade
- ...
### Funcionalidades
- ...
### Correções de bugs
- ...
### Outras mudanças
- ...
**Changelog completo:** <tag-anterior>...<nova-tag>
5. Verificações de sanidade antes de publicar
- Toda mudança que quebra compatibilidade aparece na seção ⚠️ com uma dica de migração
- Nenhuma tarefa interna é apresentada como funcionalidade para o usuário
- Nomes dos contribuidores creditados onde a convenção do repositório assim o faz
- Número da versão coincide com a tag
Convenções
- Siga o estilo de notas de versão existente do repositório, se houver — consistência supera qualquer modelo.
- Se o repositório usa
gh release --generate-notes, use a saída como rascunho inicial e refine: ela acerta a lista, mas erra os destaques. - Nunca invente mudanças que não estão no intervalo de commits. Quando o intervalo for ambíguo, pergunte quais refs comparar em vez de adivinhar.