Criando Mensagens de Commit Excelentes no Git: Melhores Práticas para um Histórico Claro

As mensagens de commit do Git são as anotações nas quais sua equipe depende quando o código quebra, o comportamento muda ou uma versão precisa ser explicada. Uma mensagem clara informa o que mudou e por que, sem forçá-lo a fazer engenharia reversa do diff.

Boas mensagens de commit não precisam ser sofisticadas. Elas precisam de uma linha de assunto útil, contexto suficiente para alterações não triviais e um estilo consistente que sua equipe possa ler meses depois.

Por que Boas Mensagens de Commit São Importantes?

Boas mensagens de commit ajudam de várias maneiras práticas:

Entendendo Mudanças: Elas fornecem contexto imediato sobre o que um commit específico introduz ou modifica, economizando tempo ao revisar código ou relembrar decisões passadas.
Depuração: Ao rastrear bugs, um histórico de commits claro permite identificar exatamente quando e por que uma mudança problemática foi introduzida.
Colaboração: Para membros da equipe que estão ingressando em um projeto ou revisando código antigo, mensagens bem escritas facilitam a compreensão da trajetória de desenvolvimento do projeto.
Revisões de Código: Elas oferecem aos revisores uma visão sobre a intenção por trás das mudanças, facilitando um feedback mais produtivo e focado.
Ferramentas Automatizadas: Muitas ferramentas do Git, como geradores de changelog e criadores de notas de versão, dependem de mensagens de commit para funcionar de forma eficaz.
Registro Histórico: Elas servem como uma forma de documentação, preservando a evolução da base de código ao longo do tempo.

A Anatomia de uma Mensagem de Commit Excelente no Git

Uma estrutura universalmente reconhecida para mensagens de commit do Git segue um padrão simples, porém poderoso: uma linha de assunto concisa seguida por um corpo opcional e mais detalhado.

A Linha de Assunto

A linha de assunto é a primeira linha da sua mensagem de commit. Deve ser um resumo breve e imperativo das mudanças. Pense nela como um título para o commit.

Diretrizes Principais para a Linha de Assunto:

Mantenha-a concisa: Cerca de 50 caracteres é uma meta útil, não um limite rígido. Mantenha o assunto curto o suficiente para ser escaneado em git log --oneline.
Use o modo imperativo: Comece com um verbo que descreva a ação, como se você estivesse emitindo um comando. Exemplos: Corrige, Adiciona, Refatora, Atualiza, Remove, Estiliza.
Capitalize a primeira palavra: A convenção padrão dita capitalizar a primeira letra da linha de assunto.
Não termine com ponto final: A linha de assunto é um título, não uma frase.
Evite usar git commit -m "mensagem" para mensagens mais longas: Embora seja conveniente para anotações curtas, pode levar a mensagens menos estruturadas. Use git commit sem argumentos para abrir seu editor para mensagens mais complexas.

Exemplos de Boas Linhas de Assunto:

feat: adiciona módulo de autenticação de usuário
fix: corrige loop infinito no processamento de dados
docs: atualiza etapas de instalação no README
refactor: simplifica carregamento de imagens
chore: atualiza dependências de desenvolvimento

O Corpo

O corpo da mensagem de commit é onde você fornece mais contexto e detalhes. Ele é separado da linha de assunto por uma linha em branco. Esta seção é opcional, mas altamente recomendada para qualquer coisa além de mudanças triviais.

Diretrizes Principais para o Corpo:

Explique o 'porquê' e o 'como': Não descreva apenas o que mudou; explique por que a mudança foi necessária e como foi implementada. Que problema este commit resolve? Qual era o comportamento anterior? Qual é o novo comportamento?
Quebre as linhas em 72 caracteres: Esta é uma convenção antiga que melhora a legibilidade em muitas ferramentas e terminais do Git.
Use marcadores para listas: Se você precisar enumerar várias mudanças ou pontos, use marcadores para maior clareza.
Referencie issues ou tickets: Se o commit estiver relacionado a um rastreador de issues (por exemplo, GitHub Issues, Jira), inclua o número do ticket para rastreabilidade.

Exemplo de uma Boa Mensagem de Commit (Assunto + Corpo):

feat: implementa página de perfil do usuário

Este commit introduz a página de perfil do usuário, permitindo que os
usuários visualizem e editem suas informações pessoais.

Anteriormente, os usuários não podiam acessar ou modificar os detalhes
do seu perfil. Esta mudança adiciona uma nova rota (`/profile`) e um
componente correspondente que busca dados do usuário na API e fornece
formulários para atualizar campos como nome, email e biografia.

Relacionado a #123.

Tipos Comuns de Mensagens de Commit (Commits Convencionais)

Seguir uma convenção para os tipos de mensagens de commit pode aumentar ainda mais a clareza e permitir ferramentas automatizadas. A especificação Commits Convencionais é um padrão popular que promove uma abordagem estruturada.

Os Commits Convencionais usam um prefixo para denotar o tipo de mudança:

feat (funcionalidade): Uma nova funcionalidade é introduzida na base de código.
fix (correção de bug): Um bug é resolvido.
docs (documentação): Mudanças apenas na documentação.
style (formatação): Mudanças que não afetam o significado do código (espaços em branco, formatação, ponto e vírgula faltando, etc.).
refactor (refatoração de código): Uma mudança no código que não corrige um bug nem adiciona uma funcionalidade.
perf (performance): Uma mudança no código que melhora o desempenho.
test (adição de testes faltantes ou correção de testes existentes): Adicionar ou corrigir testes.
build (mudanças que afetam o sistema de build ou dependências externas): Exemplos são scripts npm, webpack, etc.
ci (mudanças nos arquivos e scripts de configuração de CI): Exemplos são Travis, Circle, BrowserStack, SauceLabs, etc.
chore (tarefas de manutenção): Tarefas que não se encaixam nos outros tipos, como manutenção do repositório.

Escopo (Opcional): Um escopo pode ser adicionado ao prefixo para indicar a parte da base de código afetada. Por exemplo: feat(auth): Adiciona autenticação JWT.

Rodapé (Opcional): Use o rodapé para referenciar issues, marcar mudanças de quebra ou adicionar outros metadados. Commits Convencionais usam BREAKING CHANGE: para mudanças de quebra.

Exemplo usando Commits Convencionais:

fix(api): corrige endpoint para recuperação de dados do usuário

Anteriormente, o endpoint `/users/:id/data` retornava informações
desatualizadas. Este commit atualiza o endpoint para
`/users/:id/profile`, que busca os dados de perfil do usuário mais
atuais.

Fecha #456

Dicas para Escrever Ótimas Mensagens de Commit

Faça commits com frequência, mas de forma lógica: Faça commits pequenos e atômicos que representem uma única mudança lógica. Isso torna as mensagens mais fáceis de escrever e entender.
Escreva mensagens da perspectiva do futuro do projeto: Imagine que você está olhando para este commit daqui a seis meses. De quais informações você precisaria para entender a mudança rapidamente?
Seja específico: Evite mensagens vagas como "Atualiza código" ou "Correções de bugs." Explique precisamente o que foi atualizado ou corrigido.
Use crases para referências de código: Se você mencionar nomes de arquivos, funções ou nomes de variáveis, coloque-os entre crases (`).
Revise suas mensagens: Antes de commitar, reserve um momento para ler sua mensagem. Ela faz sentido? Está clara?

Conclusão

Escreva cada mensagem de commit para a pessoa que a lerá durante uma revisão, reversão ou incidente. Use um assunto imperativo curto, adicione um corpo quando a razão não for óbvia e mantenha cada commit focado em uma única mudança lógica.