Registos de alterações agrupados a partir de commits (não raw git log)

Porque o agrupamento de commits é importante

Quando um leitor abre uma nota de lançamento, procura por aquilo que mudou e que o afeta. Uma longa lista de SHA-1s de commits brutos e mensagens curtas obriga o olhar a saltar de um lado para o outro e a perder o ponto principal. Ao agrupar commits em baldes lógicos, dá-se ao leitor um mapa rápido de novas funcionalidades, correções de bugs e melhorias internas. Este mapa corresponde à forma como as pessoas folheiam: primeiro veem os títulos, depois decidem se precisam dos detalhes por baixo.

Expectativas do leitor

- Secções de funcionalidades respondem a “o que posso fazer agora?” - Secções de correções respondem a “qual problema foi resolvido?” - Secções de melhorias respondem a “o que melhorou sem alterar o comportamento?”

Sinal vs ruído

- Registos brutos contêm commits de mesclagem, correções de erros de digitação e ruído de refatoração. - Registos agrupados apenas mostram a intenção que é importante para os utilizadores ou equipas downstream. - A redução do 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 etiquetas

- feat: → bucket de funcionalidade - fix: → bucket de correção de bugs - perf:, refactor:, style: → bucket de melhoria - docs: → bucket de documentação (geralmente omitido nas notas visíveis para o usuário) - test: → bucket de qualidade interna

Etiquetas personalizadas

- As equipes podem adicionar security: para destacar patches que abordam vulnerabilidades. - breaking: pode ser usado para sinalizar alterações de API que requerem 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

O nosso gerador segue um pipeline de três etapas que transforma um registo git em um conjunto de grupos prontos para revisão. As etapas são determinísticas, por isso a mesma entrada sempre produz a mesma saída.

Etapa 1: analisar mensagens de commit

- Executar git log --pretty=format:%s para obter a linha de assunto de cada commit no intervalo. - Dividir o assunto no primeiro dois-pontos para isolar o prefixo e a descrição. - Se não estiver presente um dois-pontos, tratar o commit como chore: e colocá-lo em um balde interno que é ocultado do registo de alterações público.

Etapa 2: agrupar por prefixo

- Manter um mapa de prefixos conhecidos (feat, fix, perf, refactor, style, docs, test, security, breaking) para uma lista de commits. - Anexar cada commit à lista que corresponde ao seu prefixo. - Preservar 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 equipas usam prefixos combinados como feat(parser):. Removemos os parênteses e tratamos a parte esquerda como o balde principal. - Se um commit corresponder a mais de um balde (raro, mas possível com aliases personalizados) atribuímo-lo ao primeiro balde correspondente na lista de prioridade: breaking > security > feat > fix > perf > refactor > style > docs > test > chore. - A saída final é uma matriz ordenada de baldes, cada um contendo os seus commits.

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

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

Revisão da Interface de Utilizador: pré-visualização e edição de grupos

Depois do algoritmo produzir os buckets, o utilizador vê uma pré-visualização onde cada bucket é uma secção collapsível. O objetivo é permitir que o autor verifique que o agrupamento automático corresponde à intenção antes de o registo de alterações ser publicado.

Edição em linha

- Clicar na descrição de um commit a transforma num campo de texto editável. - As alterações são guardadas 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 redacção escolhida pelo ser humano.

Reordenamento por arrasto e largada

- Os buckets inteiros podem ser movidos para cima ou para baixo para refletir a narrativa de lançamento desejada. - Dentro de um bucket, os commits individuais podem ser reordenados para destacar a alteração mais importante primeiro. - A interface de utilizador emite um patch JSON que regista a nova ordem; este patch pode ser commitado juntamente com o registo de alterações para fins de auditoria.

O que isto não é

É importante ser claro sobre os limites da ferramenta para que as equipas estabeleçam expectativas realistas.

Nenhuma garantia de completude

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

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

- O agrupamento automático pode colocar incorrectamente um compromisso se o prefixo for ambíguo ou estiver em falta. - Os autores devem ainda rever as notas geradas para apanhar qualquer item mal categorizado. - A ferramenta destina-se a reduzir o esforço, não a eliminar a necessidade de um controlo humano.

Integração CI/CD

Para manter os registos de alterações atualizados, pode executar o gerador como parte do seu pipeline. A etapa produz um ficheiro que pode ser carregado como um artifacto 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 registo de alterações gerado.

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

Snippet de CI do GitLab

No ficheiro.gitlab-ci.yml, adicione um trabalho que execute o gerador e armazene o registo de alterações como um artifacto do trabalho.

- image: node:20 - variables: - GIT_STRATEGY: fetch

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

- paths: - CHANGELOG.md

Ambos os exemplos utilizam o documento público OWASP LLM Top 10 como referência para commits relacionados com segurança e o Quadro de Gestão de Riscos de IA do NIST para commits que afetam a segurança do modelo. Pode ver as referências 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 registos 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 compromisso

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

Revisão regular do grupo

- Antes de cada lançamento, abra o registo de alterações gerado e verifique se cada balde contém os compromissos esperados. - Se vir um compromisso no balde errado, edite a descrição ou adicione um prefixo personalizado para orientar o gerador. - Faça do hábito atualizar o guia de contribuição sempre que adicionar um novo prefixo personalizado para que os contribuintes futuros conheçam a convenção.

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

Mantenho uma lista de verificação escrita ao lado de cada lançamento que toca neste tópico. A lista é propositadamente simples: nomear o proprietário, nomear o artifact de evidência e nomear o rollback. Se um passo não puder produzir um ficheiro, um bilhete ou uma linha de registo, não é um passo — é um desejo.

Antes de alterar a produção

- Congele a branch ou a revisão de configuração que irá medir. - Registe 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 deve. - Abra as referências principais que irá citar: https://owasp.org/www-project-top-10-for-large-language-model-applications, https://www.nist.gov/itl/ai-risk-management-framework.

Enquanto executa a verificação

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

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 verde em linguagem de vendas que afirme a completude. - Re-executa a mesma lista de verificação quando o modelo, esquema de ferramenta ou regras de validação mudam.

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 de 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. As escolhas de arquitetura, o parecer legal e as alegações de cliente ainda precisam de um proprietário humano. Trate cada linha da lista de verificação como suporte à decisão, não como certificado.

Como explico limites aos compradores

Quando um prospecto pergunta se o produto "cobrir tudo", respondo com o limite: verificações automatizadas detectam padrões conhecidos; cadeias novas e julgamento de política ainda necessitam 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 precisar de uma segunda opinião, combine este texto com as referências abaixo e com a sua própria reprodução de teste. Não omita o passo 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

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