Introdução

Há um tempo atrás, comecei a pensar em formas de padronizar as mensagens de commit que escrevia. Motivado por questões de legibilidade e facilidade de entender sobre o que era cada commit.

Isso me trouxe alguns desafios e muitos benefícios, como por exemplo manter o foco em ter commits que resolvem um único problema, com mudanças em menos arquivos, ou que mexem em apenas um contexto da aplicação.

Pesquisando soluções e formas de escrever bons commits acabei me deparando com o padrão Conventional Commits.

O que são Conventional Commits?

Conventional Commits é um padrão de mensagens de commit que segue uma determinada estrutura. Ele define um formato para as mensagens de commit, que inclui um tipo, um escopo opcional e uma descrição.

Estrutura:

<type>[optional scope]: <description>

Exemplo prático:

feat: add new feature
fix: fix bug in code

Tipos

Cada <type> define qual tipo de mudança foi feita dentro daquele commit, esse type deve sempre seguir o mesmo padrão, como por exemplo feat, o ideal é sempre escrever nesse mesmo formato, sem deixar aberto para que outras pessoas do time escrevam feature por exemplo.

Os tipos mais comuns são:

• feat: para novas funcionalidades.
• fix: para correção de bugs.
• hotfix: para correção de falhas críticas.
• refactor: para refatoração de código.
• docs: para mudanças na documentação.
• test: para adição ou correção de testes.
• chore: para tarefas de manutenção, como atualização de dependências ou configuração de ferramentas.
• perf: para melhorias de performance.
• build: para mudanças que afetam o sistema de build ou dependências externas.
• revert: para reverter um commit anterior.
• ci: para mudanças relacionadas a integração contínua e deploy.
• tag: para criação de tags de versão.
• construction: para indicar que o trabalho está em progresso.

Mas você e seu time podem definir outros tipos como merge, release ou qualquer outro que faça sentido dentro do projeto.

Escopo (opcional)

Nas mensagens do Conventional Commits, o escopo não é obrigatório, mas pode ser utilizado para identificar a parte de código ou funcionalidade que está sendo modificada ou afetada.

Por exemplo, se você está atuando na API especificamente da parte de login, é possível colocar o escopo como (auth) ou (login) como você ou seu time estão acostumado a chamar.

Assim facilita a leitura e o entendimento de que aquele commit, pode impactar algo até que outra pessoa também esteja mexendo.

Descrição

A descrição de cada commit sempre deve ser clara e concisa, dizendo exatamente o que foi trabalhado, em algumas automações é possível adicionar o id da tarefa ou issue, para identificar.

Sempre analise o código que está comitando e escreva essa descrição de forma fácil de entender, isso pode ajudar a reverter um commit, ou entender o que foi feito, sem precisar ler o código, ou até mesmo para gerar um changelog automático.

Outros usos e convenções

Identificar quebra de versão

É possível identificar na mensagem padronizada do commit, se aquele tem um breaking change, ou seja, uma mudança que quebra a compatibilidade com versões anteriores.

Para isso é utilizado a notação com ! depois do <type> ou do <scope>.

Exemplo:

feat!: add new feature that breaks compatibility

Outra forma de utilizar, é para quem prefere commits maiores, utilizando a descrição BREAKING CHANGE em letras maiúsculas, exemplo:

feat: add new feature
BREAKING CHANGE: this change breaks compatibility with previous versions

Commit multi parágrafo

Em alguns casos, é necessário escrever uma mensagem de commit mais longa, com mais detalhes sobre as mudanças feitas.

Exemplo:

fix: prevent racing of requests

Introduce a request id and a reference to latest request. Dismiss
incoming responses other than from latest request.

Remove timeouts which were used to mitigate the racing issue but are
obsolete now.

Reviewed-by: Z
Refs: #123

Emojis

Além de seguir o padrão Conventional Commits, decidi trazer um elemento mais visual a mensagem de commits, no caso utilizando emojis.

Analisando alguns padrões na internet percebi que os emojis eram utilizados para isso e passei a adotar nos projetos junto com o conventional commits.

Na prática, eu coloco o emoji sempre antes do <type> e o emoji sempre é relacionado ao <type>.

Como por exemplo, para o <type> igual a fix, eu uso o emoji bug -> 🐛. Se for feat eu uso ✨ e assim vai.

Pra mim funciona bem dessa forma, porque só de bater o olho eu sei do que aquele commit se trata, se preciso ter uma atenção especial em algum hotfix ou coisa do tipo, ou não necessariamente por ser alguma mudança em documentação por exemplo.

Documentação no projeto

Depois de definir que eu gostaria de utilizar esse padrão nos projetos, foi imprescindível criar uma documentação, para sempre utilizar o mesmo padrão em todos os commits, e também para obter de forma fácil os emojis relacionados a cada tipo.

Vou deixar aqui abaixo a tabela de emojis e commits que eu sigo:

| Tipo             | Emoji | Exemplo de Commit                                                          |
| ---------------- | ----- | -------------------------------------------------------------------------- |
| **feat**         | ✨    | `:sparkles: feat(auth): Implementar sistema de login Task-123`             |
| **fix**          | 🐛    | `:bug: fix(api): Corrigir erro de timeout na requisição Task-456`          |
| **docs**         | 📚    | `:books: docs: Atualizar README com instruções de deploy Task-789`         |
| **style**        | 🎨    | `:art: style(components): Aplicar design system nos botões Task-101`       |
| **refactor**     | ♻️    | `:recycle: refactor(utils): Simplificar função de validação Task-202`      |
| **test**         | 🧪    | `:test_tube: test(auth): Adicionar testes para login Task-303`             |
| **chore**        | 🔧    | `:wrench: chore: Atualizar dependências do projeto Task-404`               |
| **perf**         | ⚡    | `:zap: perf(database): Otimizar consultas de usuários Task-505`            |
| **ci**           | 🧱    | `:bricks: ci: Configurar deploy automático para staging Task-606`          |
| **hotfix**       | 💥    | `:boom: hotfix: Corrigir falha crítica no pagamento Task-707`              |
| **build**        | 📦    | `:package: build: Configurar webpack para produção Task-808`               |
| **revert**       | ⏪    | `:rewind: revert: Reverter mudanças no componente Header Task-909`         |
| **tag**          | 🔖    | `:bookmark: tag: Criar tag de versão v1.2.0 Task-910`                      |
| **construction** | 🚧    | `:construction: construction: Trabalho em progresso no dashboard Task-911` |
| **Merge**        | 🔀    | `:twisted_rightwards_arrows: Merge: mensagem padrão de merge`              |

Com esse padrão documentado, fica fácil de obter o emoji que desejo para o commit com o type correto.

Dessa forma é possível deixar os commits padronizados, fáceis de ler e entender, e também mais visuais, o que pode ajudar a identificar rapidamente o tipo de mudança que foi feita, sem precisar ler a descrição completa do commit.

Conclusão

Ter um padrão de commits é muito útil em todo projeto, seja ele pequeno ou grande, isso ajuda a manter a organização e a legibilidade do histórico de commits, além de facilitar a colaboração entre os membros do time.

Faz sentido analisar o seu escopo e entender qual padrão pode se aplicar melhor.

Definido um padrão, recomendo que documente, sem a documentação fica mais fácil dispersar e voltar a escrever commits de forma antiga.

Caso tenha alguma sugestão de melhoria nesse artigo, entre em contato comigo no Linkedln :)