Guia Prático: Padrões de Commits

Em qualquer projeto, é essencial ter um histórico claro e compreensível das mudanças que acontecem ao longo do tempo. Uma das ferramentas que tornam isso possível é o sistema de controle de versão GIT, onde cada alteração é registrada através de um “commit”. O commit semântico é uma convenção que busca melhorar a clareza e a eficácia desses registros, deixando de forma objetiva cada mensagem registrada no projeto.

Isso facilita não apenas a leitura e compreensão, mas também fornece informações úteis para ferramentas automatizadas que podem processar este formato padronizado.

Problemas com commits não-semânticos

Dificuldade em entender mudanças: Mensagens de commit vagas ou ambíguas como “Corrigido bug” ou “Atualizações” não fornecem contexto suficiente. Isso pode tornar difícil para os desenvolvedores entenderem o racional ou o impacto de uma mudança, especialmente em projetos maiores.

Falta de Padrão: Sem uma convenção definida, cada desenvolvedor tem sua própria maneira de escrever commits, levando a um histórico inconsistente e por vezes confuso.

Atraso na Identificação de Bugs: Sem entender claramente o propósito de cada commit, pode ser mais desafiador rastrear a origem de um bug ou comportamento inesperado no código.

Estrutura do commit semântico

O formato geral de um commit semântico é:

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

Tipo: Define a natureza da alteração, e.g., feat, fix, docs.
Escopo: É opcional e contextualiza onde a mudança ocorre, e.g., auth, api, db.
Mensagem: Descreve a mudança de maneira concisa.

Tipos de Commit Semântico

feat: Esta tag é usada quando uma nova funcionalidade ou recurso é adicionado ao projeto. Exemplo: feat(api): cria rota de cadastro de usuários
fix: Usado quando um bug é corrigido. Exemplo: fix(auth): resolve problema na validação do token JWT
docs: Alterações ou adições à documentação. Exemplo: docs(readme): atualiza instruções de setup do docker-compose
style: Refere-se a correções de estilo como formatação, falta de ponto e vírgula, etc., que não afetam a lógica do código. Exemplo: style(controllers): remove espaços em branco não utilizados
refactor: Mudanças no código que não introduzem novas funcionalidades nem corrigem bugs. Pode ser uma reestruturação ou uma otimização. Exemplo: refactor(db): migra conexão para injeção de dependência
perf: Melhorias de performance no código. Exemplo: perf(queries): adiciona indexação para reduzir tempo de busca no banco
test: Quando se adicionam testes faltantes ou se corrigem testes existentes. Exemplo: test(api): adiciona teste unitário para o serviço de login
chore: Mudanças regulares ou de manutenção, como atualizações de dependências. Exemplo: chore(deps): atualiza pacote Microsoft.EntityFrameworkCore para v8.0

O escopo nem sempre é algo obrigatório, porém pelo menos deve seguir o padrão com tipo: mensagem do commit.

Exemplo de um commit:

git commit -m “feat: implementing login button in header”

Ou, se prefere seguir em português, também sem problemas:

git commit -m “feat: implementando botão de login no header”

Mudanças Críticas (Breaking Changes)

Se o seu commit introduz uma mudança drástica que quebra a compatibilidade com versões anteriores (uma alteração no contrato de uma API, por exemplo), a convenção pede que você adicione um ! logo após o tipo ou escopo.

Exemplo: feat(api)!: altera a estrutura de resposta do endpoint de usuários

Mensagem de Commit

A mensagem de commit deve ser clara, concisa e descrever efetivamente o que foi feito.

Concisão é o segredo: Tente manter a mensagem curta, mas informativa. O ideal é que ela não exceda 40 a 50 caracteres.
Evite linguagem redundante: Frases como “Adicionei…” ou “Eu mudei…” são desnecessárias. Em vez disso, vá direto ao ponto: fix: resolve problema de login com e-mail.
Use o tempo presente: Isso mantém a consistência e a leitura fácil. Em vez de “adicionado” ou “corrigido”, use “adiciona” ou “corrige”.

Dica Extra: Ferramentas para automatizar

Para manter esse padrão em projetos maiores ou trabalhando em equipe, você pode usar ferramentas que facilitam ou até forçam a padronização:

Conventional Commit (Plugin JetBrains): Para quem desenvolve no Rider ou outras IDEs da JetBrains, esse plugin é excelente. Ele adiciona uma interface direto na janela de commit da IDE para você selecionar o tipo, escopo e preencher a mensagem, gerando tudo no padrão automaticamente.
Commitizen: Em vez de digitar o git commit -m "...", o Commitizen abre um menu interativo no seu terminal perguntando o tipo, escopo e mensagem, e monta o commit semântico perfeitamente para você.
Commitlint: Funciona como um “fiscal”. Ele impede que você ou alguém da sua equipe faça um commit se a mensagem não estiver seguindo as regras do commit semântico.

Referências

Se quiser se aprofundar no assunto, aqui estão os materiais por onde aprendi sobre o tema e a documentação oficial da convenção: