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:
- ✅ 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 :)
