Habilidade de Construtor de Changelog para Conventional Commits

--- name: conventional-commits-changelog-builder description: Transforma um git log no formato Conventional Commits em uma seção de release pronta para colar no Keep a Changelog - Added, Changed, Deprecated, Removed, Fixed, Security - com escopos, links de issues e commits e um bloco de breaking changes. Sinaliza breaking changes sem notas de migração, commits não conformes e fixup, reverts e duplicatas, e sugere a próxima versão SemVer. Inclui um builder Python offline com stdlib e --self-test. --- # Conventional Commits Changelog Builder Você ajuda mantenedores a transformar os commits desde a última tag em uma entrada de changelog que as pessoas realmente conseguem ler. Escrever manualmente significa rolar um log, adivinhar quais commits importam e esquecer a única breaking change escondida em um rodapé. Gerar cegamente copia cada erro de digitação, commit WIP e feature revertida para o release. Você analisa os commits, mapeia para as seções do Keep a Changelog, lista exatamente o que foi deixado de fora e por quê, e diz qual versão o release deve receber. ## Arquivos nesta skill - `scripts/changelog_build.py` - lê `git log` (formato padrão), `git log --oneline` ou uma exportação de registros `%x1f`/`%x1e`; analisa cabeçalhos `type(scope)!: description` e rodapés `BREAKING CHANGE:`; agrupa em Added / Changed / Deprecated / Removed / Fixed / Security com um bloco BREAKING CHANGES; cancela reverts que estão no intervalo, pula merges, remove duplicatas, sinaliza commits fixup/WIP e não conformes com um cabeçalho sugerido; vincula issues, commits e o intervalo de comparação; sugere o bump SemVer (ciente de 0.x); pode inserir a seção em um CHANGELOG.md existente (apenas stdlib Python 3.8+) - `references/commit-to-changelog-mapping.md` - a tabela de tipo -> seção, regras de breaking change, regras de bump e os códigos de descoberta CC01-CC10 - `references/release-hygiene.md` - escrever entradas para usuários, notas de migração, o que fazer com histórico não conforme e verificações de CI - `templates/release-notes-review.md` - a revisão para devolver junto com a seção - `examples/git-log.txt` - 21 commits de um CLI fictício (tidyq) desde v2.3.1: duas breaking changes, uma correção de segurança, uma depreciação, um revert, uma duplicata de cherry-pick, um fixup, um WIP e um commit simples "Fixed ..." - `examples/CHANGELOG.md` - o changelog existente do projeto (Unreleased + 2.3.1 + 2.3.0) - `examples/changelog-report.md` - a saída real do builder nesse log ## Fluxo de trabalho ### 1. Obtenha o intervalo de commits Peça a última tag lançada e exporte tudo depois dela, do mais novo para o mais antigo: ``` git log v2.3.1..HEAD > commits.txt git log v2.3.1..HEAD --format='%H%x1f%s%x1f%b%x1e' > commits.txt # mais seguro: mantém corpos, sem adivinhação de parsing ``` Também peça a versão atual, a data do release, a URL do repositório (para links), o prefixo da tag (`v` por padrão) e se commits internos (refactor, docs, ci, chore, test) devem ser listados. Um fluxo de squash-merge é ideal: um PR = um commit = uma linha. ### 2. Execute o builder ``` python3 scripts/changelog_build.py examples/git-log.txt --current 2.3.1 --date 2026-11-03 --repo-url https://github.com/tidyq/tidyq python3 scripts/changelog_build.py commits.txt --current 2.3.1 --insert CHANGELOG.md > CHANGELOG.new.md python3 scripts/changelog_build.py commits.txt --current 0.9.4 --include-internal --json python3 scripts/changelog_build.py --self-test ``` Saída 0 = pronto para tag, 1 = descobertas altas, 2 = entrada inválida. Sem um shell, aplique `references/commit-to-changelog-mapping.md` manualmente: analise cada cabeçalho, mapeie o tipo para a seção, colete rodapés `!` e `BREAKING CHANGE:`, cancele reverts e então escolha o bump mais alto. ### 3. Corrija as descobertas antes de criar a tag - CC03 (alta): um commit com `!` sem rodapé `BREAKING CHANGE:` não dá aos usuários um caminho de migração. Escreva a nota (o que quebra, o que fazer em vez disso) na seção. - CC08 (alta): commits não conformes que parecem features ou correções estão faltando no changelog. Adicione-os manualmente com o cabeçalho sugerido e ative uma verificação de commit-lint. - CC07: commits fixup/WIP devem ser esmagados antes do release; CC04: reverts de releases mais antigos precisam de uma frase explicando o porquê. - CC01/CC02/CC05/CC06: redação e conformidade; corrija no texto do changelog, não reescrevendo histórico publicado. ### 4. Edite para humanos O builder dá a você a estrutura correta, não boa prosa. Reescreva entradas como efeitos visíveis ao usuário ("Export escreve Parquet por padrão" em vez de "refactor writer"), mescle entradas que descrevem uma mudança, mantenha escopos que os usuários reconhecem e coloque o bloco BREAKING CHANGES onde ninguém possa perder. Veja `references/release-hygiene.md`. ### 5. Entregue Preencha `templates/release-notes-review.md`: versão e por quê, a seção final, as notas de migração, o que foi deixado de fora e acompanhamentos (commitlint, verificação de título de PR). Com `--insert`, devolva o CHANGELOG.md atualizado; o arquivo original nunca é modificado. ## Exemplo de resultado Em `examples/git-log.txt` (atual 2.3.1) o builder lê 21 commits, 85% conformes, e sugere **3.0.0**: `feat(export)!` torna Parquet o padrão (com um rodapé BREAKING CHANGE adequado) e `fix(config)!` remove o arquivo de configuração INI sem nenhuma nota de migração (CC03, alta). "Fixed crash when the config file is empty" não é um Conventional Commit e silenciosamente ficaria de fora do changelog (CC08, alta; sugerido `fix: crash when the config file is empty`). A correção de vazamento de token vai para Security, a depreciação `--legacy-dates` para Deprecated, a feature de temas de cor e seu revert se cancelam, a correção de BOM com cherry-pick é listada uma vez, e o merge, fixup, WIP e 5 commits internos são listados como deixados de fora. ## Regras - Nunca invente entradas: cada linha vem de um commit, e cada commit está ou na seção ou na lista "deixados de fora". - Uma breaking change sempre recebe uma nota de migração e o bump major (minor enquanto em 0.x); nunca a esconda em Changed. - Correções de segurança vão em Security mesmo quando o tipo do commit é `fix`. - Não reescreva histórico publicado para corrigir mensagens de commit; corrija o texto do changelog e adicione uma verificação de lint para o futuro. - Mantenha o release mais novo no topo, datas como AAAA-MM-DD e um link de comparação por versão. - A versão é uma sugestão: o mantenedor decide, especialmente para mudanças de comportamento tipadas como `fix`.