O histórico de um repositório é a documentação mais honesta de um projeto. Commit messages genéricos destroem esse ativo silenciosamente.
- O que um bom commit message responde
- Commits atômicos
- Convenções que ajudam
- O teste do git log
“fix”, “update”, “ajustes”, “wip”. Esses são os commit messages mais comuns em repositórios de qualquer tamanho. São também completamente inúteis como documentação.
O histórico de um repositório é a única fonte que registra não apenas o que mudou, mas quando mudou e — se o commit message for bom — por que mudou. Destruir esse ativo com mensagens genéricas é um custo que aparece meses depois, quando alguém precisa entender por que uma decisão foi tomada.
O que um bom commit message responde
Um commit message eficaz responde três perguntas implícitas: o que foi feito, onde foi feito e por quê foi feito.
“fix button” não responde nenhuma das três. “Fix submit button disabled state on mobile Safari” responde as duas primeiras. “Fix submit button disabled state on mobile Safari — input type=date triggers blur before submit on iOS 16” responde as três.
A terceira resposta é a mais valiosa e a mais raramente escrita.
Commits atômicos
Um commit que muda cinquenta arquivos por razões não relacionadas é impossível de reverter parcialmente, difícil de revisar e impossível de entender pelo message.
Commits atômicos — cada um com uma única razão de existir — tornam o histórico navegável. É possível encontrar exatamente quando um comportamento foi introduzido, reverter uma mudança específica sem afetar o resto, e entender o raciocínio por trás de cada decisão.
Convenções que ajudam
Conventional Commits é uma especificação simples: prefixo de tipo (feat:, fix:, docs:, refactor:), escopo opcional entre parênteses, e descrição em tempo presente.
Não é obrigatório adotar o padrão exato. É obrigatório ter algum padrão, documentado, que todo o time segue. Consistência no histórico é mais valiosa do que a convenção específica escolhida.
O teste do git log
Uma forma de avaliar a qualidade do histórico de um repositório: abrir o git log sem olhar os diffs e tentar entender o que aconteceu no projeto nos últimos três meses só pelas mensagens de commit.
Se não for possível, o histórico não está cumprindo sua função.
