Predefinições de tom para devs e clientes para os mesmos commits

Por que separar pré-configurações de tom?

Eu comecei este projeto porque vi equipes desperdiçando tempo reescrevendo a mesma entrada de changelog para dois leitores diferentes. Engenheiros precisam ver o que mudou no código, quais arquivos foram alterados e quais APIs internas quebradas. Gerentes de produto, equipe de suporte e usuários finais se importam com o que a mudança significa para eles: novos recursos, bugs corrigidos, desempenho melhorado ou limites removidos. Um único tom não pode atender bem a ambos os grupos. Ao criar duas pré-configurações distintas que operam na mesma lista de commits, mantemos a fonte de verdade inalterada enquanto entregamos mensagens personalizadas. Esta abordagem também permite que o rótulo SemVer permaneça a única fonte de significado contratual, porque o rótulo está anexado ao grupo de commits, não à redação.

Predefinição de tom do desenvolvedor: detalhe-primeiro

Detalhe no nível de commit

Quando a predefinição de desenvolvedor está ativa, a IA expande cada commit em uma sentença que inclui o caminho do arquivo, a função ou classe modificada e a natureza da alteração (adição, exclusão, refatoração). Por exemplo, um commit que corrige um ponteiro nulo em src/api/user.go se torna: "Corrigido dereferenciamento de ponteiro nulo em GetUserByID quando o ID de entrada é zero, adicionado cláusula de guarda e teste unitário."

Linkando para sistemas de rastreamento

Se a mensagem de commit contém um ID de problema (por exemplo, ABC-123), a predefinição o envolve em um link para o rastreador, supondo que a equipe tenha configurado a URL base. Isso permite que os engenheiros acessem diretamente a discussão ou o documento de design sem sair do registro de alterações.

Incluindo contexto técnico

A predefinição adiciona quaisquer avisos relevantes do compilador, alterações na cobertura de testes ou deltas de benchmark de desempenho que apareceram na execução do CI associada ao commit. Isso fornece uma verificação rápida de saúde para a área modificada.

Verificações de segurança e conformidade para saída de LLM

Como o texto é gerado por um modelo de linguagem, eu o executo em um filtro de segurança leve que verifica o conteúdo proibido. O filtro referencia a OWASP LLM Top 10 para riscos de injeção de prompt e o NIST AI Risk Management Framework para orientação sobre como gerenciar alucinações e viés. Se um segmento dispara uma regra, ele é marcado para revisão humana antes da publicação.

Lista de exemplos para uma versão típica

- Adicionada interface RetryPolicy em src/retry/policy.go para permitir estratégias de retrocesso plugáveis. - Removida estrutura LegacyCache depreciada de src/cache/legacy.go; todos os chamadores migrados para LRUCache. - Corrigida condição de corrida em WorkerPool.Start onde um canal nulo poderia ser fechado duas vezes; adicionado guarda de mutex. - Atualizado módulo Go github.com/stretchr/testify de v1.7.0 para v1.8.2 para incluir patch de segurança para pacote assert. - Adicionados benchmarks para JSONEncoder mostrando redução de 12% no tamanho de alocação para payloads abaixo de 10KB.

Predefinição de tom do cliente: benefício em primeiro lugar

Linguagem focada no resultado

Com a predefinição do cliente, a IA reescreve cada confirmação em uma sentença que descreve o que o usuário pode fazer agora ou qual problema foi resolvido. Jargões técnicos são substituídos por termos simples. A mesma correção de ponteiro nulo se torna: "Os usuários não verão mais um erro ao inserir um ID de valor zero no campo de pesquisa de usuário."

Evitando identificadores internos

Hashes de confirmação, nomes de branch e números de problemas internos são omitidos, a menos que sejam parte de uma flag de recurso pública ou de um endpoint de API versionado que os clientes possam referenciar. O objetivo é manter o ruído baixo.

Destacando o impacto no usuário

Se uma confirmação melhora o desempenho, a predefinição traduz o ganho de benchmark em uma declaração visível para o usuário: "Os tempos de carregamento de página agora são até 15% mais rápidos em dispositivos móveis." Se uma confirmação remove um limite, ela é lida: "Agora você pode fazer upload de arquivos de até 100 MB em vez do limite anterior de 25 MB."

Linkando para documentação pública

Quando uma alteração toca um endpoint de API pública ou uma opção de configuração, a predefinição adiciona um link para a seção de documentação relevante, supondo que o site de documentação siga um padrão de URL previsível (por exemplo, https://docs.example.com/api/v2/users).

Lista de exemplos para o mesmo lançamento

- A lógica de retry agora se adapta a problemas temporários de rede, reduzindo uploads com falha em conexões instáveis. - A implementação antiga de cache foi removida; o novo cache usa menos memória e limpa entradas obsoletas automaticamente. - Corrigimos um crash raro que poderia ocorrer quando muitos trabalhadores começavam ao mesmo tempo. - Biblioteca de terceiros atualizada para abordar um aviso de segurança; nenhuma ação é necessária de sua parte. - Respostas JSON agora são mais leves, o que reduz o uso de dados em conexões medidoras.

De diff de commit para duas narrativas

Análise e agrupamento

O pipeline começa executando git log --pretty=format:%H %s %b --since="1 semana atrás" para coletar commits desde a última tag. Cada commit é analisado para seu tipo de commit convencional (feat, fix, perf, refactor, etc.) e escopo. Commits com o mesmo tipo e implicações de SemVer são agrupados juntos porque compartilharão o mesmo aumento de versão.

Aplicando prompts específicos de tom

Para cada grupo, eu crio duas prompts: uma ajustada para o preset de desenvolvedor, outra para o preset de cliente. A prompt do desenvolvedor pede por "uma descrição detalhada e técnica que inclui nomes de arquivos, símbolos e quaisquer alterações relevantes de teste ou benchmark". A prompt do cliente pede por "uma explicação concisa e orientada para benefícios que evita jargão interno e se concentra no que o usuário experimenta". A mesma lista de commits alimenta ambas as prompts, garantindo que os fatos subjacentes permaneçam idênticos.

Revisão com intervenção humana

A saída da IA é direcionada para um editor de rascunho onde um mantenedor pode aceitar, editar ou rejeitar cada frase. Eu descobri que a maioria das edições são ajustes menores de redação em vez de alterações factuais, o que mostra que o modelo é bom em permanecer fiel à diff de origem. Após a revisão, o rascunho é renderizado em Markdown e, em seguida, em HTML para publicação.

Tabela: mapeamento de tipos de commit convencionais para frases de tom

Tipo de commit | Exemplo de frase para desenvolvedor | Exemplo de frase para cliente feat | Adicionado método ExportCSV ao ReportService que transmite linhas para reduzir o uso de memória. | Agora você pode baixar relatórios como arquivos CSV diretamente do botão de exportação. fix | Resolvido deadlock em JobQueue.Push quando um trabalho nulo foi enfileirado sob alta carga. | Os trabalhos não mais ficarão presos quando o sistema estiver ocupado. perf | Substituído lookup O(n²) em TagIndex.Find por um mapa de hash, reduzindo a latência de 12 ms para 0,8 ms para 10 k tags. | As buscas de tags agora são consideravelmente mais rápidas, especialmente com bibliotecas grandes. refactor | Extraído interface PasswordValidator de AuthHandler para permitir regras de força plugáveis. | Os requisitos de senha agora podem ser ajustados sem alterar o código de login principal. docs | Atualizado API.md com nova descrição de endpoint PATCH /users/:id e payload de exemplo. | O centro de ajuda agora mostra como atualizar parcialmente um perfil de usuário.

Preservando o significado do SemVer em tons diferentes

As regras de incremento de versão permanecem ancoradas nos commits

A etiqueta SemVer é determinada exclusivamente pelos tipos de commits convencionais no grupo: um feat dispara um incremento menor, um fix um patch, e uma alteração de quebra um incremento maior. Como os presets de tom não alteram as mensagens de commit ou seus tipos, o número de versão resultante é idêntico seja qual for a versão do desenvolvedor ou do cliente que você lê.

Consistência de contrato

Trato a etiqueta SemVer como o contrato entre o produtor e o consumidor do software. O registro de alterações é apenas uma expressão legível por humanos desse contrato. Ao manter o contrato intacto, as equipes podem confiar em ferramentas automatizadas (como bots de lançamento ou verificadores de dependência) para interpretar a versão corretamente, enquanto o registro de alterações de tom duplo atende aos dois públicos sem criar ambiguidade.

Exemplo de um lançamento principal

Suponha que um commit adicione BREAKING CHANGE: remove a API legada v1. O preset de desenvolvedor observará as exatas exclusões de arquivos e as etapas de migração necessárias. O preset de cliente explicará que o ponto de extremidade da API antiga não está mais disponível e apontará os usuários para a documentação da v2. Em ambos os casos, a versão passa de 2.4.1 para 3.0.0, preservando o significado contratual.

O que isso não é

Quero deixar claro os limites dessa abordagem para que você possa ter expectativas realistas.

- Isso não garante que cada frase gerada será perfeita em termos de tom; ocasionalmente, frases muito técnicas podem aparecer no rascunho do cliente ou linguagem de benefícios vagas podem aparecer no rascunho do desenvolvedor. A revisão humana ainda é necessária. - Não é um substituto 100% para um escritor técnico dedicado ou um marketer de produtos. A IA acelera a primeira versão, mas a nuances, a voz da marca e as declarações legais ainda precisam do toque de uma pessoa. - Isso não elimina a necessidade de higiene de commit clara. Se as mensagens de commit forem vagas ou não tiverem a estrutura de commit convencional, os grupos serão menos precisos e a saída será menos útil. - Não é uma ferramenta mágica que irá satisfazer automaticamente todos os reguladores ou diretrizes de acessibilidade. Os controles de segurança que eu adicionei são básicos; você ainda deve realizar sua própria revisão de conformidade. - Isso não promete que o changelog nunca perderá uma alteração. Se um commit for omitido do log do git (por exemplo, devido a um clone raso ou a um filtro errado), ele não aparecerá em nenhum dos tons.

Referências

- OWASP LLM Top 10 - NIST AI Risk Management Framework

Leituras relacionadas

- Registros de alterações agrupados de commits (não log git bruto) — Changelog AI - A matriz de tópicos de micro-SaaS de IA LX