Conventional Commits: como escrever boas mensagens de commit

Abra o histórico de um projeto antigo e você provavelmente vai encontrar mensagens como ajustes, wip e agora vai. Elas não dizem nada para quem precisa entender o código daqui a seis meses. O Conventional Commits é um padrão simples que resolve isso.

O formato

Cada mensagem segue esta estrutura:

<tipo>(<escopo opcional>): <descrição>

<corpo opcional>

<rodapé opcional>

Exemplos:

feat(login): adiciona entrada com Microsoft
fix(api): corrige timeout na exportação de CSV
docs: explica como rodar os testes localmente

Os tipos mais usados

feat: uma funcionalidade nova para quem usa o produto.
fix: correção de bug.
docs: só documentação.
refactor: mudança no código que não altera o comportamento.
perf: melhoria de desempenho.
test: testes novos ou corrigidos.
build e ci: sistema de build, dependências e pipelines.
chore: tarefas que não entram nas categorias acima.

Escopo e descrição

O escopo diz onde a mudança aconteceu: feat(checkout), fix(auth). Combine os escopos com o time.
Escreva a descrição no imperativo e no presente: adiciona, corrige, remove.
Seja específico: corrige cálculo do frete para CEP sem número é melhor que corrige frete.
Mantenha a primeira linha curta, com até uns 72 caracteres. Detalhes vão no corpo.

Corpo e rodapé

O corpo explica o porquê da mudança, não o que mudou linha a linha (isso o diff já mostra). O rodapé guarda referências, como o número da tarefa:

fix(checkout): recalcula o frete ao trocar o endereço

O frete ficava com o valor do endereço anterior quando a pessoa
trocava o CEP depois de escolher a entrega.

Refs: #482

Breaking changes

Quando a mudança quebra compatibilidade, marque com ! depois do tipo ou com BREAKING CHANGE: no rodapé:

feat(api)!: remove o endpoint /v1/pedidos

BREAKING CHANGE: use /v2/pedidos, que pagina os resultados.

Por que vale a pena

O histórico vira documentação: dá para ler o que mudou entre duas versões.
Ferramentas como semantic-release e release-please geram o changelog automaticamente.
A versão também pode ser calculada sozinha: fix sobe o patch, feat sobe o minor e breaking change sobe o major.
A revisão de código fica mais fácil, porque o tipo já diz o que esperar do diff.

Como adotar no time

Combine os tipos e escopos e escreva no README ou no guia de contribuição.
Valide as mensagens com o commitlint, no hook de commit ou no pipeline.
Comece pelos tipos principais (feat, fix, docs, refactor) e adicione os outros conforme precisar.

Mensagens de commit com IA no GitMuninn

Escrever uma boa mensagem toda vez dá trabalho. No GitMuninn, a IA lê o diff e sugere a mensagem do commit, que você revisa antes de confirmar. Ela só roda quando você pede, recebe apenas o diff e a mensagem, e nada fica gravado em servidor. São 20 mensagens por mês no plano Grátis e sem limite no Pro e no Business.