por Tiago Silva

Quem trabalha com versionamento de projetos usando Git provavelmente já se viu refletindo sobre qual seria o título mais adequado para determinado commit. Isso é saudável e esperado, mas não pode se transformar em uma tarefa que consuma tempo demais.

Ter um método e uma padronização clara para esse momento não apenas agiliza o trabalho, como também proporciona outros benefícios. Para isso foi criada a especificação Conventional Commits, uma convenção para escrever mensagens de commit de forma clara, consistente e funcional.

Infográfico mostrando como compor uma mensagem de commit a partir do tipo, do escopo e da ação realizada.

Estrutura de uma mensagem

Uma mensagem segue, de forma simplificada, esta estrutura:

<tipo>[escopo opcional]: <descrição>

O tipo indica a natureza da mudança;
O escopo informa onde ela ocorreu; e,
A descrição resume a ação realizada.

Por exemplo:

fix(serial): fix connection timeout
feat(adc): add voltage calibration
docs(examples): improve infographic example

BREAKING CHANGES

Para indicar que o commit possui incompatibilidades com versões anteriores, adicione ! imediatamente antes dos dois-pontos. Exemplo:

feat(api)!: remove deprecated endpoint

Como os commits seguem um padrão previsível, passam a servir como informação estruturada para pessoas e ferramentas.

Benefícios

1. Gerar CHANGELOGs automaticamente

Ferramentas e scripts conseguem identificar quais mudanças representam novas funcionalidades, correções ou breaking change e, a partir disso, montar automaticamente um histórico de alterações para cada versão.

2. Incrementar versões automaticamente

Se você utiliza Semantic Versioning, seus commits podem ser usados para decidir se a próxima versão deve incrementar PATCH, MINOR ou MAJOR:

Commit Incremento Exemplo
fix PATCH 1.2.0 → 1.2.1
feat MINOR 1.2.0 → 1.3.0
breaking change MAJOR 1.2.0 → 2.0.0

3. Comunicar claramente a natureza das mudanças

Só pelo início da mensagem já é possível entender rapidamente o que aconteceu. Por exemplo, fix(serial) indica uma correção relacionada à interface serial, enquanto feat(adc) indica uma nova funcionalidade relacionada ao ADC. Isso facilita a comunicação entre desenvolvedores, usuários e outras partes interessadas.

4. Facilitar contribuições ao projeto

Um histórico de commits padronizado é muito mais fácil de navegar. Quem chega ao projeto consegue encontrar rapidamente correções, novas funcionalidades, refatorações e mudanças importantes sem precisar abrir cada commit para descobrir o que aconteceu.

Em resumo, Conventional Commits transforma o histórico do Git de uma simples sequência de mensagens em informação estruturada, que pode ser entendida tanto por pessoas quanto por ferramentas automáticas.