Registro de alterações agrupadas a partir de commits (não log git bruto)

Por que o agrupamento de commits é importante

Quando um leitor abre uma nota de lançamento, ele procura por aquilo que mudou e o afeta. Uma longa lista de SHA-1s crus e mensagens curtas força o olho a pular e perder o ponto. Ao agrupar commits em baldes lógicos, você fornece ao leitor um mapa rápido de novos recursos, correções de bugs e melhorias internas. Esse mapa corresponde à forma como as pessoas folheiam: primeiro veem os títulos, então decidem se precisam dos detalhes abaixo.

Expectativas do leitor

- Seções de recursos respondem “o que posso fazer agora?” - Seções de correção respondem “qual problema foi resolvido?” - Seções de melhoria respondem “o que melhorou sem alterar o comportamento?”

Sinal versus ruído

- Registros crus contêm commits de mesclagem, correções de erros de digitação e ruído de refatoração. - Registros agrupados mostram apenas a intenção que importa para os usuários ou equipes downstream. - A redução de ruído corta o tempo necessário para avaliar um lançamento de minutos para segundos.

Mapeamento de commits convencionais para grupos

A especificação de commits convencionais fornece um prefixo previsível que sinaliza a intenção. Ao ler o prefixo, você pode decidir a qual bucket um commit pertence sem parsear a mensagem completa.

Prefixos de tag

- feat: → bucket de recurso - fix: → bucket de correção de bug - perf:, refactor:, style: → bucket de melhoria - docs: → bucket de documentação (freqüentemente omitido das notas visíveis ao usuário) - test: → bucket de qualidade interna

Tags personalizadas

- Equipes podem adicionar security: para destacar patches que abordam vulnerabilidades. - breaking: pode ser usado para marcar alterações de API que exigem migração. - Qualquer prefixo extra deve ser documentado no guia de contribuição do projeto para que o gerador saiba onde colocá-lo.

Algoritmo: agrupamento de commits por tags semânticas

Nosso gerador segue um pipeline de três etapas que transforma um log do git em um conjunto de grupos prontos para revisão. As etapas são determinísticas, então a mesma entrada sempre produz a mesma saída.

Etapa 1: parsear mensagens de commit

- Execute git log --pretty=format:%s para obter a linha de assunto de cada commit no intervalo. - Divida o assunto no primeiro caractere de dois pontos para isolar o prefixo e a descrição. - Se não houver dois pontos presentes, trate o commit como chore: e coloque-o em um bucket interno que é ocultado do changelog público.

Etapa 2: agrupar por prefixo

- Mantenha um mapa de prefixos conhecidos (feat, fix, perf, refactor, style, docs, test, security, breaking) para uma lista de commits. - Anexe cada commit à lista que corresponde ao seu prefixo. - Preserve a ordem original de commit dentro de cada lista para que etapas posteriores possam mostrar uma visão cronológica.

Etapa 3: resolver sobreposições

- Algumas equipes usam prefixos combinados como feat(parser):. Removemos os parênteses e tratamos a parte esquerda como o bucket principal. - Se um commit corresponder a mais de um bucket (raro, mas possível com aliases personalizados), atribuímos a ele o primeiro bucket correspondente na lista de prioridade: breaking > security > feat > fix > perf > refactor > style > docs > test > chore. - A saída final é uma matriz ordenada de buckets, cada um contendo seus commits.

Etapa | Entrada | Saída 1 | assuntos do log do git | pares de prefixo + descrição 2 | pares de prefixo + descrição | buckets de commits 3 | buckets de commits | buckets ordenados, deduplicados e prontos para exibição

Para ver como o algoritmo funciona na prática, você pode tentá-lo em qualquer repositório que siga o formato de commits convencionais. O gerador irá exibir os mesmos grupos que você criaria manualmente, mas em uma fração do tempo.

Revisão da Interface do Usuário: pré-visualização e edição de grupos

Após o algoritmo produzir os buckets, o usuário vê uma pré-visualização onde cada bucket é uma seção collapsível. O objetivo é permitir que o autor verifique se o agrupamento automático corresponde à intenção antes que o registro de alterações seja publicado.

Edição inline

- Clicar na descrição de um commit a transforma em um campo de texto editável. - As alterações são salvas localmente e podem ser usadas para reatribuir um commit a um bucket diferente arrastando a linha editada. - As descrições editadas são armazenadas como substituições, para que as futuras execuções do gerador mantenham a redação escolhida pelo ser humano.

Reordenação por arrasto e solta

- Buckets inteiros podem ser movidos para cima ou para baixo para refletir a narrativa de lançamento desejada. - Dentro de um bucket, commits individuais podem ser reordenados para destacar a alteração mais importante primeiro. - A interface do usuário emite um patch JSON que registra a nova ordem; esse patch pode ser commitado junto com o registro de alterações para fins de auditoria.

O que isso não é

É importante esclarecer os limites da ferramenta para que as equipes estabeleçam expectativas realistas.

Nenhuma garantia de completude

- O gerador só vê o que está no intervalo de commits que você fornece. - Se uma alteração for feita fora do controle de versão (por exemplo, uma ajuste manual de configuração do servidor), ela não aparecerá. - Não escaneamos rastreadores de problemas, documentos de design ou canais de comunicação externos.

Não é um substituto para a revisão manual

- O agrupamento automático pode colocar incorretamente um commit se o prefixo for ambíguo ou estiver faltando. - Os autores ainda devem examinar as notas geradas para capturar qualquer item mal categorizado. - A ferramenta é destinada a reduzir o esforço, não para eliminar a necessidade de um gate humano.

Integração de CI/CD

Para manter os registros de alterações atualizados, você pode executar o gerador como parte do seu pipeline. A etapa produz um arquivo markdown que pode ser carregado como um artifact ou usado para criar uma versão do GitHub.

Exemplo de ação do GitHub

Adicione uma etapa ao seu fluxo de trabalho que verifica o código, configura o Node, executa o gerador e, em seguida, cria uma versão com o registro de alterações gerado.

- usa: actions/checkout@v4 - executa: npm ci - executa: npx ai-changelog-generator --from ${{ github.event.before }} --to ${{ github.sha }} --output CHANGELOG.md - usa: softprops/action-gh-release@v2 - com: - tag_name: ${{ github.ref_name }} - nome: Lançamento ${{ github.ref_name }} - body_path: CHANGELOG.md

Trecho de CI do GitLab

No arquivo.gitlab-ci.yml, adicione um trabalho que execute o gerador e armazene o registro de alterações como um artifact do trabalho.

- imagem: node:20 - variáveis: - GIT_STRATEGY: fetch

- npm ci - npx ai-changelog-generator --from $CI_COMMIT_BEFORE_SHA --to $CI_COMMIT_SHA --output CHANGELOG.md

- caminhos: - CHANGELOG.md

Ambos os exemplos usam o documento público OWASP LLM Top 10 como referência para commits relacionados à segurança e o Quadro de Gerenciamento de Riscos de IA do NIST para commits que afetam a segurança do modelo. Você pode vê-los referenciados inline:

- https://owasp.org/www-project-top-10-for-large-language-model-applications - https://www.nist.gov/itl/ai-risk-management-framework

Melhores práticas para manter registros de alterações agrupados

Mesmo com automação, alguns hábitos mantêm a saída útil ao longo da vida de um projeto.

Higiene de commits

- Sempre inicie uma mensagem de commit com um prefixo convencional. - Se um commit afeta várias áreas, divida-o em commits separados para que cada um tenha uma intenção clara. - Inclua uma descrição breve após o dois-pontos que explique o impacto visível ao usuário.

Revisão regular do grupo

- Antes de cada lançamento, abra o registro de alterações gerado e verifique se cada bucket contém os commits esperados. - Se você vir um commit no bucket errado, edite a descrição ou adicione um prefixo personalizado para direcionar o gerador. - Faça do hábito atualizar o guia de contribuição sempre que adicionar um novo prefixo personalizado, para que os contribuidores futuros conheçam a convenção.

Lista de verificação do operador para registros de alterações agrupados de commits (não log raw do git)

Mantenho uma lista de verificação escrita ao lado de cada lançamento que toca nesse tópico. A lista é propositadamente simples: nomear o proprietário, nomear a evidência do artifact e nomear o rollback. Se uma etapa não puder produzir um arquivo, um ticket ou uma linha de log, não é uma etapa — é um desejo.

Antes de alterar a produção

- Congele o branch ou a revisão de configuração que você medirá. - Registre o modo de falha atual com uma entrada concreta e uma saída concreta. - Confirme qual identidade o trabalho é executado e se essa identidade pode alcançar dados que não deveria. - Abra as referências principais que você citará: https://owasp.org/www-project-top-10-for-large-language-model-applications, https://www.nist.gov/itl/ai-risk-management-framework.

Enquanto você executa a verificação

- Prefira um caminho reprodutível em vez de dez capturas de tela anedóticas. - Escreva o resultado seguro esperado antes de acionar a ferramenta ou consulta. - Capture o comando exato, prompt, schema ou regex em teste — não uma paráfrase. - Se o sistema puder agir (enviar, escrever, excluir, transferir), exija um limite de confirmação na mesma passagem.

Depois de terminar

- Arquive o risco residual com um proprietário e uma data, mesmo quando a varredura estiver limpa. - Não converta um sinal de verificação verde em linguagem de vendas que afirme completude. - Execute a mesma lista de verificação quando o modelo, a ferramenta de schema ou as regras de validação mudarem.

Sinal | O que registrar | Parar o envio? Escrita ou envio inesperado | Nome da ferramenta, args, identidade | Sim até que seja controlado Falta de confirmação em ação destrutiva | Caminho de chamada e bypass | Sim Texto não confiável tratado como instrução | Superfície de origem e ação resultante | Sim para alcance do agente Varredura limpa, julgamento aberto | Itens adiados + proprietário | Apenas se o caminho central for seguro

ai-changelog-generator ajuda com a primeira passagem mensurável. Escolhas de arquitetura, aprovação legal e alegações voltadas para o cliente ainda precisam de um proprietário humano. Trate cada linha da lista de verificação como suporte à decisão, não como um certificado.

Como explico limites aos compradores

Quando um prospecto pergunta se o produto "cobri tudo", respondo com o limite: verificações automatizadas capturam padrões conhecidos; cadeias novas e julgamento de política ainda precisam de revisão. Essa honestidade mantém a carga de suporte baixa e mantém o blog alinhado com o que o produto realmente faz.

Se você precisar de uma segunda opinião, combine este texto com as referências abaixo e com sua própria reprodução de teste. Não pule a etapa de reprodução apenas porque um modelo escreveu um resumo confiante.

Referências

- https://owasp.org/www-project-top-10-for-large-language-model-applications - https://www.nist.gov/itl/ai-risk-management-framework

Leituras relacionadas

- Tom de desenvolvedor versus tom de cliente para os mesmos commits — Changelog AI - A matriz de tópicos de Micro-SaaS de LX AI