Nomear commits com padrão não é burocracia: é o que separa um histórico legível de um amontoado de mensagens vagas. Quando cada commit responde a pergunta "o que mudou e por quê", a manutenção deixa de ser arqueologia. Abaixo, 11 padrões práticos, do mais essencial ao complementar.
1. Conventional Commits: o tipo como verbo
O padrão mais adotado começa com um tipo obrigatório: feat (nova funcionalidade), fix (correção), docs, style, refactor, test, chore. Ele comunica a intenção em uma palavra. O Conventional Commits é citado por projetos como base para automação de changelog e versionamento semântico.
2. Escopo entre parênteses: onde a mudança ocorre
Depois do tipo, um escopo opcional delimita o módulo: feat(auth), fix(api), docs(README). Isso evita que o leitor abra o diff para descobrir o contexto. Em times grandes, o escopo reduz conflitos de interpretação.
3. Descrição imperativa e curta
A descrição deve completar a frase "este commit irá...": add, fix, remove, update. Escrever "adiciona validação de email" é mais direto que "adicionando validação" ou "validação adicionada". Limite o título a 50 caracteres, como sugere a convenção do próprio Git.
4. Corpo do commit: o porquê, não o quê
O título diz o quê; o corpo explica o porquê. Inclua contexto, decisões e alternativas descartadas. Um commit sem corpo que muda lógica complexa gera dívida técnica para quem fizer manutenção seis meses depois.
5. Rodapé para breaking changes e issues
Use BREAKING CHANGE ou o prefixo ! (feat!:) para mudanças que quebram compatibilidade. Referencie issues com Fix #123 ou Closes #45. Isso conecta o commit ao sistema de tickets e permite rastrear o motivo original.
6. Um commit, uma responsabilidade
Commits atômicos, que alteram apenas uma coisa, facilitam o bisect e o revert. Se você fez três mudanças não relacionadas, separe em três commits. O critério é simples: se uma mudança precisar ser desfeita, ela deve ser um commit isolado.
7. Prefixos por categoria além do básico
Tipos extras como perf, ci, build, security ajudam em contextos específicos. Um commit perf(cache) comunica otimização; security(auth) alerta para vulnerabilidade. Cada time define seu vocabulário, desde que documentado.
8. Convenção para branches que vira commit
Alguns times usam o mesmo padrão de nomenclatura de branch no commit: fix/autenticacao-2fa vira fix(auth): corrige validação do 2FA. Isso cria consistência entre o fluxo de trabalho e o histórico.
9. Idioma único no time
Escolha português ou inglês e mantenha. Misturar idiomas dificulta buscas e automações. O importante é que o padrão seja registrado em um guia acessível ao time.
10. Ferramentas de validação automática
Ferramentas como commitlint e husky bloqueiam commits fora do padrão, como descreve o repositório de padrões de commits. Isso evita que a convenção vire letra morta após as primeiras semanas.
11. Mensagens que contam história
Um bom commit é uma unidade de narrativa: o que foi feito, por que e qual o impacto. Ao revisar o histórico, cada entrada deve permitir entender a evolução do projeto sem abrir o código.
Como escolher o padrão certo
Para projetos novos ou times pequenos, o Conventional Commits puro já resolve. Times grandes se beneficiam de escopo e validação automática. O critério final é simples: o padrão que seu time consegue manter por meses, não o mais completo no papel.
FAQ
O que é Conventional Commits?
É uma especificação que define um formato de mensagem de commit com tipo, escopo opcional e descrição. O formato mais comum é tipo(escopo): descrição, como feat(api): adiciona endpoint de login. Ele permite automação de changelogs e versionamento semântico.
Qual a diferença entre feat e fix?
feat indica uma nova funcionalidade para o usuário. fix indica uma correção de bug. Ambos são tipos do Conventional Commits e influenciam o versionamento: feat incrementa a versão menor, fix a versão de patch.
Como escrever um commit de refatoração?
Use o tipo refactor para mudanças que não alteram comportamento externo. Exemplo: refactor(auth): extrai função de validação. Se a refatoração mudar comportamento, use feat ou fix conforme o impacto.
Commits devem ser em português ou inglês?
Não há regra universal. O time deve escolher um idioma e manter consistência. Times internacionais usam inglês; times locais, português. O importante é que a busca no histórico funcione para todos.
O que é um commit atômico?
É um commit que altera apenas uma responsabilidade lógica. Se você precisa reverter apenas uma mudança, ela deve estar isolada. Commits atômicos facilitam bisect, code review e manutenção.
Como validar padrão de commit automaticamente?
Ferramentas como commitlint, husky e lint-staged verificam a mensagem antes do commit ser aceito. Elas bloqueiam formatos fora do padrão e exibem erro imediato, como descrito em guias de padroes de commits.