Como escrever mensagens de commits no Git

Se você nunca viu/escreveu mensagens de commits como estas acima, parabéns.

Apesar de a maioria dos desenvolvedores escrever boas mensagens, não podemos generalizar: sempre tem alguém para ~~provar que a zueira não tem limites~~ estragar a estatística.

Como escrever boas mensagens

Devemos escrever a mensagem no presente? No futuro? Em português? Em inglês? São infinitas as formas as quais uma mensagem de commit pode ser escrita.

Antes de mais nada, você deveria escrever as mensagens de commits em inglês. Eu escrevi um artigo com 8 motivos para programar em inglês, e os mesmos motivos se aplicam aqui.

O correto é escrever na forma imperativa. Ou seja, você precisa sempre estar apto a completar a seguinte frase:

If applied, this commit will your subject line here

Tradução livre: "Se aplicado, esse commit vai seu resumo aqui"

Exemplos:

Encontrei exemplos bacanas nesse artigo (em inglês) e vou listá-los abaixo:

✅ If applied, this commit will Refactor subsystem X for readability
✅ If applied, this commit will Update getting started documentation
✅ If applied, this commit will Remove deprecated methods
✅ If applied, this commit will Release version 1.0.0
✅ If applied, this commit will Merge pull request #123 from user/branch

Note como isso não fica legal escrevendo de forma não-imperativa:

❌ If applied, this commit will Fixed bug with Y
❌ If applied, this commit will Changing behavior of X
❌ If applied, this commit will More fixes for broken stuff
❌ If applied, this commit will Sweet new API methods

Nota: não é preciso adicionar um ponto no final da mensagem.

Resumo e corpo da mensagem do commit

Encontrei nesse artigo um modelo (em inglês) de mensagem para commits:

Capitalized, short (50 chars or less) summary

More detailed explanatory text, if necessary.  Wrap it to about 72
characters or so.  In some contexts, the first line is treated as the
subject of an email and the rest of the text as the body.  The blank
line separating the summary from the body is critical (unless you omit
the body entirely); tools like rebase can get confused if you run the
two together.

Write your commit message in the imperative: "Fix bug" and not "Fixed bug"
or "Fixes bug."  This convention matches up with commit messages generated
by commands like git merge and git revert.

Further paragraphs come after blank lines.

- Bullet points are okay, too

- Typically a hyphen or asterisk is used for the bullet, followed by a
  single space, with blank lines in between, but conventions vary here

- Use a hanging indent

Basicamente a primeira linha - conhecida como summary (resumo) - deve conter 50 ou menos caracteres, enquanto que as linhas seguintes - conhecidas como body (corpo) - pode conter quantas linhas forem necessárias, limitadas a 72 caracteres por linha.

No corpo, eu costumo incluir explicações detalhadas, links, listas e qualquer outra coisa relevante quando necessário.

Por que uma boa mensagem importa?

Alguns motivos:

Caso um bug seja introduzido, uma boa mensagem de commit facilita a identificação de onde/quando isso aconteceu;
Se você reverter um commit, a mensagem será Revert "mensagem original", deixando claro o que está sendo revertido;
Boas mensagens se tornam útias ao exibir listas de commits através de comandos como git blame, git log, git shortlog, etc.

Para finalizar, a regra principal é o bom senso. Se você usar como desculpa que não teve 10 segundos pra pensar em uma boa mensagem, eu vou certamente duvidar :)