Guia Definitivo de Boas Práticas para Mensagens de Commit

Este guia serve como referência técnica e padronização para equipes de desenvolvimento de software. Uma mensagem de commit clara, estruturada e consistente não apenas facilita a leitura do histórico do projeto (git log), mas também viabiliza automações críticas no pipeline de CI/CD, como geração automática de notas de lançamento (changelogs), cálculo de versionamento semântico (SemVer) e facilidade na execução de investigações com comandos como git bisect.

1. Estrutura Geral e a Regra dos 50/72 Caracteres

A anatomia clássica de uma mensagem de commit de alto nível divide-se em três partes: Assunto/Título, Corpo e Rodapé, respeitando limites de largura de caracteres para garantir legibilidade perfeita tanto no terminal (evitando quebras automáticas desformatadas) quanto em interfaces web (como GitHub e GitLab).

():
  • Linha de Assunto (máx. 50 caracteres): Funciona como a manchete do commit. Deve ser direta e dizer o que a alteração faz.
  • Linha em branco: Obrigatória entre o assunto e o corpo. Sem ela, muitas ferramentas do ecossistema Git tratam o texto inteiro como um único parágrafo contínuo.
  • Corpo (máx. 72 caracteres por linha): Espaço para detalhar o contexto e a motivação técnica da solução. Não foque em como o código foi feito (o diff já mostra as linhas alteradas), mas sim no porquê da escolha adotada.
  • Rodapé: Reservado para metadados, links de rastreabilidade (issues/PRs) e avisos de compatibilidade.

2. Tipos Principais (Padrão Conventional Commits)

A especificação Conventional Commits padroniza o prefixo da mensagem, categorizando a natureza da entrega:

  • feat (feature): Introdução de uma nova funcionalidade no sistema, perceptível pelo usuário ou pela API que consome a aplicação.
  • fix: Correção de um bug, falha ou comportamento inesperado em produção/desenvolvimento.
  • refactor: Reestruturação interna do código existente sem alterar o comportamento externo (não adiciona novas funcionalidades nem corrige bugs; foca em legibilidade, modularização e boas práticas).
  • perf (performance): Alterações no código voltadas estritamente para otimizar tempo de resposta, consumo de memória, throughput ou uso de CPU.
  • chore: Modificações em rotinas auxiliares, tarefas de manutenção, automações de build, scripts de suporte ou atualização de dependências de ambiente que não afetam a regra de negócio.
  • docs: Atualizações exclusivas em documentação (README, manuais de API, comentários estruturais no código).
  • test: Criação de novos testes automatizados (unitários, integração, E2E) ou correção/refatoração de testes existentes sem alterar o código de produção.
  • style: Ajustes visuais de formatação que não alteram a semântica do código (espaçamentos, quebras de linha, vírgulas, padronização de linter).

3. Regras Práticas para uma Boa Mensagem

  1. Use o modo imperativo no título: Redija o assunto como se estivesse dando uma instrução direta ao Git (ex.: feat: add suporte a webhook e não feat: adicionado suporte ou feat: adicionando suporte). Pense na frase: "Se aplicado, este commit irá: [seu título aqui]".
  2. Limite a primeira linha a 50 caracteres: Títulos longos são truncados nas interfaces gráficas e dificultam a visualização rápida com git log --oneline.
  3. Não finalize o título com ponto final: O assunto funciona estritamente como um cabeçalho/título sintético.
  4. Foque no "porquê" no corpo: Descreva os problemas que motivaram a mudança, as alternativas avaliadas e os trade-offs técnicos assumidos.
  5. Vincule tarefas no rodapé: Conecte o commit ao issue tracker com palavras-chave aceitas pelos servidores Git (ex.: Closes #123, Fixes #45, Resolves #89).

4. Exemplos Práticos de Aplicação

Exemplo 1: Commit Simples (Apenas Título)

Indicado para alterações atômicas e de contexto autoexplicativo:

git commit -m "fix(auth): impede redirecionamento incorreto no logout"

Exemplo 2: Commit Completo (Título, Corpo e Rodapé)

Ideal para tarefas de desenvolvimento que exigem histórico rastreável e explicação de regras de negócio:

git commit -m "feat(mapa): adiciona selecao de multiplos pontos de obra Permite ao usuario selecionar mais de um ponto simultaneamente no mapa para calcular a distancia total percorrida antes de iniciar a gravacao. O limite maximo de marcadores por sessao foi fixado em 50 para evitar degradacao de renderizacao na camada de overlay. Closes #42"

Exemplo 3: Breaking Change (Quebra de Compatibilidade)

Utiliza a exclamação ! após o escopo/tipo e o bloco BREAKING CHANGE: no rodapé para indicar que a alteração quebra versões anteriores da API ou interface:

git commit -m "feat(api)!: altera formato de retorno de coordenadas para GeoJSON BREAKING CHANGE: O endpoint /api/obras/pontos agora retorna objetos GeoJSON padrao em vez de arrays simples com latitude e longitude. Clientes legados devem atualizar os parsers de resposta." 

5. Referências e Leituras Essenciais

  • Conventional Commits Specification (v1.0.0): Documentação oficial em português com os padrões de prefixos, convenções semânticas e exemplos de automação para releases.
  • How to Write a Git Commit Message (Chris Beams): Artigo de referência na comunidade que detalha as sete regras de ouro da mensagem de commit:
    1. Separe o assunto do corpo com uma linha em branco.
    2. Limite a linha de assunto a 50 caracteres.
    3. Comece a linha de assunto com letra maiúscula.
    4. Não termine a linha de assunto com ponto final.
    5. Use o modo imperativo na linha de assunto.
    6. Quebre as linhas do corpo do texto em 72 caracteres.
    7. Use o corpo do texto para explicar o que e por que, em vez de como.