Guia de Bolso: Como Escrever Commits Profissionais com Conventional Commits

Introdução

Recentemente influenciado por um amigo passei a frequentar palestras de eventos da comunidade dev local, o que tem sido uma experiência muito massa, e no Encontro de Devs da comunidade PHP com Rapadura de Abril/2025, um dos participantes comentou que já deixou de contratar pois ao olhar o Github do candidato haviam barbaridades nos commits dele como “enviando essa merda de novo”, chegando a conclusão que se ele não cuidava bem do próprio repositório imagina o da empresa.

Ao ouvir isso lembrei que há algum tempo atrás eu já havia sentido a curiosidade de saber como escrever bons commits depois de assistir a um vídeo do Fábio Akita sobre Git, foi ai que encontrei o Conventional Commits que é uma especificação para adicionar significado legível as mensagens de commit para humanos e máquinas.

Já adianto que não existe uma forma certa de escrever commit, o normal é que a equipe que você vai trabalhar ou um projeto open source que venha a colaborar, vai instruir como os commits devem ser feitos, e podem ou não estar em acordo com as especificações. A minha recomendação é que nos seus projetos pessoais adote essa convenção, pois vai facilitar a sua leitura em momento posterior e passar mais credibilidade para quem consultar seu trabalho.

🏗️ Estrutura do commit

<tipo>(escopo*): <mensagem curta>

[ corpo* ]

[ rodapé* ]

* Campos opcionais

Exemplo:

feat(cliente): permite múltiplas localizações por cliente

Adiciona suporte para salvar mais de uma localização por cliente no backend.

🔤 Tipos mais comuns de commits

🔖 Escopo

Indica onde a mudança é feita, apesar de opcional, é recomendado principalmente em projetos maiores.

Exemplo:

api, auth, infra

feat(auth): adiciona expiração do token JWT

📃 Corpo do commit

Use quando precisar explicar com mais detalhes a mudança, muito útil para commits mais complexos.

Exemplo:

fix(cliente): corrigir erro ao salvar coordenadas

O problema acontecia quando o campo 'latitude' vinha vazio. Adicionada validação antes de salvar.

👟 Rodapé

Use para:

• Refenciar issues:

Fecha #123

• Indicar breaking changes

BREAKING CHANGE: muda estrutura da tabela de clientes

Outros tipos de rodapé diferentes de BREAKING CHANGE: <descrição> devem serguir a convenção similar ao trailers do Git.

Exemplo

fix: corrige pequenos erros de digitação no código

veja o ticket para mais detalhes sobre os erros de digitação corrigidos

Revisado por: Ana Alice
Refs #321

💡Boas práticas

1. Escreva no modo imperativo: adiciona, corrige, remove. Tenha em mente que a mensagem a ser transmitida é algo similar a: “Ao aplicar esse commit ele corrige erro ao criar um novo cliente sem sobrenome”.
2. Seja específico: "ajustes na tela" não explica o que você fez.
3. Prefira commits pequenos e bem definidos: o ideal é que seja um commit por modificação/feature. Se for uma mudança muito grande, divida em contextos menores.
4. Não escreva linhas com mais de 100 caracteres, isso facilita a leitura da mensagem no Github assim como em várias outras ferramentas Git.
5. Caso seu commit tenha um breaking change, adicione um ! logo após o tipo do commit.

Exemplo

feat(api)!: permite envio de foto de perfil na criação do usuário

BREAKING CHANGE: o endpoint agora espera receber um multipart/form-data ao invés de JSON

Exemplos prontos

feat(user): adiciona endpoint de cadastro

fix(auth): corrige verificação de token expirado

refactor(router): extrai validação do token para um middleware

docs(readme): adiciona instruções de setup local

test(user): adiciona testes unitários para login

chore: atualiza dependencias do composer

⁉️Curiosidades

• Os tipos de commits são baseados nas convenções do Angular
• O Conventional Commits se encaixa com o Semantic Versioning, outra especificação mas para versionamento de software

🎁Bônus

Gostou do conteúdo? Disponibilizei para download uma versão em PDF desse guia para que você possa consultar offline.

Baixar Guia de Bolso

Leia também: