Guia Completo de Commits

Guia detalhado sobre Conventional Commits com casos avançados, boas práticas e exemplos do dia a dia.

TIP

Para uma visão rápida, veja Conventional Commits.

Estrutura Detalhada

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

[corpo opcional]

[rodapé(s) opcional(is)]

Componentes

tipo: obrigatório, sempre em minúsculas
escopo: opcional, entre parênteses
!: opcional, indica breaking change
descrição: obrigatória, até 72 caracteres, sempre em minúsculas
corpo: opcional, explicação detalhada
rodapé: opcional, metadados (breaking changes, issues, co-autores)

Tipos em Detalhes

`feat` - Nova Funcionalidade

Qualquer adição de funcionalidade ao sistema.

bash

# Simples
feat: adiciona exportação de relatório em PDF

# Com escopo
feat(relatorio): adiciona filtro por período

# Com corpo explicativo
feat(notificacao): adiciona canal de notificação via WhatsApp

Integra com API do WhatsApp Business para enviar notificações
de vencimento de equipamentos diretamente ao usuário.

Quando usar:

✅ Nova tela/página
✅ Novo endpoint de API
✅ Nova funcionalidade em feature existente
✅ Novo campo em formulário (se muda comportamento)

Quando NÃO usar:

❌ Preparação para feature futura (use chore ou refactor)
❌ Apenas mudança visual sem nova função (use style)

`fix` - Correção de Bug

Correção de comportamento incorreto ou inesperado.

bash

# Bug simples
fix: corrige cálculo de dias corridos

# Bug específico
fix(crud): corrige salvamento duplicado ao clicar duas vezes

# Com referência a issue
fix(api): corrige timeout em requisições longas

Aumenta timeout de 30s para 60s em endpoints de relatório.

Refs: #123

Quando usar:

✅ Corrige erro/exceção
✅ Corrige comportamento incorreto
✅ Corrige validação quebrada
✅ Corrige problema de performance

Quando NÃO usar:

❌ Melhoria de código que já funciona (use refactor)
❌ Adição de validação nova (use feat)

`docs` - Documentação

Alterações apenas em documentação (código não muda).

bash

# README
docs: atualiza instruções de instalação

# API
docs(api): adiciona exemplos de uso dos endpoints

# Comentários no código
docs(service): adiciona JSDoc nos métodos principais

Quando usar:

✅ README, CHANGELOG, guias
✅ Comentários de código (JSDoc, PHPDoc)
✅ Documentação de API
✅ Diagramas, arquitetura

Importante: Se mudou código + documentação, use o tipo do código (ex: feat) e mencione a doc no corpo.

`style` - Estilo e Formatação

Mudanças que não afetam o significado do código.

bash

# Formatação
style: ajusta indentação e espaçamento

# Lint
style: corrige warnings do ESLint

# Imports
style: organiza imports em ordem alfabética

Quando usar:

✅ Formatação (espaços, tabs, quebras de linha)
✅ Ponto e vírgula, vírgulas
✅ Ordenação de imports
✅ Ajustes de lint/prettier

Quando NÃO usar:

❌ Mudanças de CSS/UI visíveis ao usuário (considere feat ou fix)
❌ Mudança de lógica mesmo que pequena

`refactor` - Refatoração

Mudança de código que não adiciona feature nem corrige bug.

bash

# Simplificação
refactor: simplifica lógica de validação de CPF

# Extração
refactor(service): extrai lógica de cálculo para método separado

# Reorganização
refactor: move helpers para pasta utils

Quando usar:

✅ Melhoria de código existente
✅ Extração de métodos/classes
✅ Renomeação significativa
✅ Simplificação de lógica complexa

Quando NÃO usar:

❌ Se corrigiu um bug junto (use fix)
❌ Se adicionou funcionalidade (use feat)

`perf` - Performance

Melhoria de performance sem mudar funcionalidade.

bash

# Query
perf(database): otimiza query de listagem de equipamentos

# Cache
perf: adiciona cache Redis para consultas frequentes

# Algoritmo
perf(relatorio): substitui loop nested por map para melhor performance

Quando usar:

✅ Otimização de queries
✅ Adição de cache
✅ Melhoria de algoritmo
✅ Redução de uso de memória

`test` - Testes

Adição ou correção de testes (sem mudar código de produção).

bash

# Novo teste
test: adiciona testes unitários do serviço de autenticação

# Correção
test(crud): corrige mock no teste de atualização

# Cobertura
test: aumenta cobertura do módulo de notificações

`chore` - Tarefas de Manutenção

Build, CI/CD, dependências, configurações.

bash

# Dependência
chore: atualiza Laravel para v11

# CI/CD
chore(ci): adiciona validação de commits no pipeline

# Config
chore: configura ESLint para o projeto

# Build
chore(docker): atualiza imagem base para PHP 8.3

Quando usar:

✅ Atualização de dependências
✅ Mudanças no CI/CD
✅ Configuração de ferramentas
✅ Scripts de build
✅ .gitignore, .env.example

`revert` - Reverter Commit

Reverte um commit anterior.

bash

revert: reverte "feat: adiciona login com biometria"

Este commit reverte abc1234.
Motivo: biometria causando crash em dispositivos antigos.

Formato recomendado:

bash

revert: reverte "<mensagem do commit original>"

Este commit reverte <hash>.
Motivo: <explicação do por quê>

Escopo: Quando Usar ou Não

✅ Use escopo quando:

bash

# Módulo específico
feat(auth): adiciona recuperação de senha
fix(crud): corrige validação de datas

# Área do sistema
feat(api): adiciona endpoint de estatísticas
refactor(frontend): reorganiza componentes

# Feature específica
feat(relatorio): adiciona gráfico de barras
fix(notificacao): corrige envio de email

❌ Não use escopo quando:

bash

# Múltiplos módulos afetados
refactor: padroniza tratamento de erros em toda aplicação
style: aplica formatação geral do código

# Escopo muito genérico
feat(app): adiciona funcionalidade  # muito vago
fix(bug): corrige problema  # redundante

# Mudança global
chore: atualiza todas as dependências
docs: atualiza README e documentação da API

Dica de Ouro

Se você tem dúvida se deve usar escopo, não use. É melhor um commit claro sem escopo do que um commit com escopo errado.

Breaking Changes - Detalhado

Quando é Breaking Change?

bash

✅ Mudança de assinatura de API pública
✅ Remoção de endpoint/método
✅ Mudança de estrutura de dados obrigatória
✅ Mudança de comportamento esperado
✅ Upgrade forçado de dependência

❌ Adição de novo endpoint (compatível)
❌ Adição de campo opcional
❌ Fix de bug (restaura comportamento esperado)
❌ Refatoração interna (usuário não nota)

Formato 1: Usando `!`

bash

feat!: remove autenticação básica

feat(api)!: muda estrutura de resposta dos endpoints

Formato 2: Usando `BREAKING CHANGE:` (Recomendado)

bash

feat(api): adiciona autenticação obrigatória em todos endpoints

BREAKING CHANGE: todos os endpoints agora exigem header Authorization
com token JWT. Autenticação básica foi removida.

Migração:
1. Obter token em POST /auth/login
2. Adicionar header: Authorization: Bearer <token>
3. Atualizar todas chamadas de API

Refs: #456

Por quê usar o formato 2?

✅ Permite explicar o impacto
✅ Permite dar instruções de migração
✅ Mais visível em changelogs
✅ Ferramentas de release detectam melhor

Múltiplos Breaking Changes

bash

feat(api): reestrutura endpoints de usuário

BREAKING CHANGE: estrutura de resposta foi alterada
Antes: { user: {...} }
Agora: { data: {...} }

BREAKING CHANGE: endpoint /users/list foi removido
Use /users com query params ?page=1&limit=10

Corpo do Commit

Use o corpo quando a descrição não for suficiente.

Quando usar corpo:

bash

# Explicar o "por quê"
fix(api): aumenta timeout de requisições

Requisições de relatório estavam falhando com timeout após 30s.
Aumentado para 60s baseado em análise de logs onde 95% das
requisições completam entre 45-50s.

# Explicar decisões técnicas
refactor(database): migra de UUID v4 para ULID

ULIDs são ordenáveis por tempo de criação, melhorando performance
de queries com ORDER BY. Mantém mesmas características de UUID
(único, 128 bits) mas com melhor performance em índices.

# Listar múltiplas mudanças relacionadas
feat(crud): adiciona validações avançadas

- CPF com validação de dígito verificador
- Data de nascimento não pode ser futura
- Email com verificação de domínio válido
- Telefone aceita formato nacional e internacional

Formatação do corpo:

Linha em branco entre descrição e corpo
Máximo 72 caracteres por linha
Use listas quando aplicável
Seja objetivo mas completo

Rodapés

Referência a Issues

bash

# Issue única
Refs: #123

# Múltiplas issues
Refs: #123, #456, #789

# Fecha issue automaticamente (GitLab)
Closes: #123
Fixes: #123
Resolves: #123

Co-autoria (Pair Programming)

bash

feat(auth): implementa autenticação com JWT

Co-authored-by: João Silva <joao@senai.br>
Co-authored-by: Maria Santos <maria@senai.br>

Reviewed-by

bash

feat(api): adiciona endpoint de estatísticas

Reviewed-by: Pedro Oliveira <pedro@senai.br>

Múltiplos rodapés

bash

fix(notificacao): corrige envio duplicado de emails

Problema ocorria quando cron executava simultaneamente.
Adicionado lock distribuído com Redis para prevenir concorrência.

Refs: #234
Reviewed-by: Ana Costa <ana@senai.br>

Casos Especiais

Merge Commits

Evite criar merge commits manualmente. Use rebase ou squash.

Se inevitável:

bash

Merge branch 'feature/nova-funcionalidade' into develop

Work in Progress (WIP)

bash

# Durante desenvolvimento
WIP: implementando autenticação com Google

# Quando finalizar, faça rebase interativo e corrija:
feat(auth): adiciona autenticação com Google

Commits de Configuração Inicial

bash

chore: configuração inicial do projeto

- Estrutura de pastas
- Docker compose
- Variáveis de ambiente
- GitLab CI/CD

Boas Práticas

1. Commits Atômicos

Cada commit deve representar uma mudança lógica completa.

bash

# ❌ Errado: múltiplas mudanças não relacionadas
feat: adiciona CRUD de usuários, corrige bug de login, atualiza README

# ✅ Certo: commits separados
feat(crud): adiciona CRUD de usuários
fix(auth): corrige validação de senha no login
docs: atualiza README com novos endpoints

2. Descrição Clara e Específica

bash

# ❌ Vago
fix: corrige bug
feat: adiciona funcionalidade

# ✅ Específico
fix(crud): corrige salvamento duplicado ao submeter formulário duas vezes
feat(relatorio): adiciona exportação de relatório em formato Excel

3. Verbo no Imperativo

bash

# ❌ Errado
feat: adicionado filtro de data
fix: corrigido bug de validação

# ✅ Certo
feat: adiciona filtro de data
fix: corrige validação de CPF

4. Capitalização - Regras do Mercado

PADRÃO ANGULAR/CONVENTIONAL COMMITS

Seguimos rigorosamente o padrão Angular, adotado pelo mercado e pela spec Conventional Commits.

Regra Geral: Tudo Minúscula

A descrição sempre começa com letra minúscula:

bash

# ❌ Errado
feat: Adiciona novo endpoint
fix: Corrige problema
docs: Atualiza documentação

# ✅ Certo
feat: adiciona novo endpoint
fix: corrige problema de timeout
docs: atualiza documentação

Exceções: Nomes Próprios e Siglas

Mantêm capitalização original:

Nomes de tecnologias e empresas:

bash

feat(auth): adiciona login com Google
chore(docker): atualiza imagem do Node para v20
feat(api): implementa autenticação JWT
feat: adiciona integração com PostgreSQL
fix: corrige conexão com Redis

Siglas e acrônimos:

bash

fix(api): corrige timeout na API
chore(ci): atualiza pipeline do CI/CD
feat(http): adiciona suporte a HTTP/2
docs(rest): documenta endpoints REST

Arquivos especiais (convenção):

bash

docs: atualiza README
docs: atualiza CHANGELOG
chore: corrige sintaxe no .gitignore

Conceitos técnicos: sempre minúscula

bash

# ✅ Certo
docs(development): adiciona definition of done
docs(git): documenta conventional commits
feat(relatorio): adiciona exportação de relatório
fix(crud): corrige validação de formulário

# ❌ Errado
docs(development): adiciona Definition of Done
docs(git): documenta Conventional Commits

Resumo da Regra

Elemento	Capitalização	Exemplo
Tipo	Minúscula	`feat` não `Feat`
Escopo	Minúscula	`(auth)` não `(Auth)`
Descrição	Minúscula	`adiciona login` não `Adiciona login`
Nomes Próprios	Original	`Google`, `Node`, `PostgreSQL`
Siglas	Maiúscula	`API`, `CI/CD`, `JWT`, `HTTP`
Arquivos especiais	Original	`README`, `CHANGELOG`
Conceitos	Minúscula	`definition of done`, `conventional commits`

Regra Prática

Antes de commitar, pergunte:

É nome de empresa/tecnologia? → Mantém capitalização (Google, Redis)
É sigla conhecida? → Mantém maiúscula (API, JWT)
É arquivo especial? → Mantém capitalização (README)
É conceito/ação/descrição? → Minúscula (adiciona, definition of done)

Quando em dúvida: Use minúscula. É sempre mais seguro.

5. Sem Ponto Final

bash

# ❌ Errado
feat: adiciona login com Google.

# ✅ Certo
feat: adiciona login com Google

Erros Comuns

❌ Tipo em maiúscula

bash

FEAT: adiciona funcionalidade  # errado
feat: adiciona funcionalidade  # certo

❌ Espaço entre tipo e :

bash

feat : adiciona funcionalidade  # errado
feat: adiciona funcionalidade   # certo

❌ Descrição muito longa

bash

feat: adiciona funcionalidade de exportação de relatórios em múltiplos formatos incluindo PDF e Excel com suporte a filtros  # 120+ caracteres

# Certo: usar corpo
feat: adiciona exportação de relatórios em múltiplos formatos

Suporta PDF e Excel com filtros de período, status e usuário.

❌ Commit genérico

bash

fix: corrige bugs          # qual bug?
feat: adiciona código      # qual código?

# Certo
fix(auth): corrige validação de token expirado
feat(crud): adiciona validação de CPF no formulário

❌ Misturar mudanças

bash

feat: adiciona CRUD + corrige bug de login + atualiza README

# Certo: 3 commits separados

❌ Capitalização incorreta

bash

# Errado
feat: Adiciona endpoint de usuários
docs: Atualiza README do projeto
feat(api): Implementa autenticação

# Certo
feat: adiciona endpoint de usuários
docs: atualiza README do projeto
feat(api): implementa autenticação

Exemplos do Mundo Real

Exemplo 1: Feature Completa

bash

feat(equipamento): adiciona notificação de vencimento

Implementa sistema de notificação automática via email quando
equipamento está próximo do vencimento (7 dias antes).

Funcionalidades:
- Cron diário verificando vencimentos
- Template de email personalizável
- Configuração de dias de antecedência
- Log de notificações enviadas

Refs: #567
Co-authored-by: Carlos Silva <carlos@senai.br>

Exemplo 2: Bug Crítico

bash

fix(api): corrige vazamento de memória em endpoint de relatório

Query estava carregando todos registros em memória antes de
processar. Alterado para usar cursor/stream processando em lotes
de 1000 registros.

Impacto: reduz uso de memória de 2GB para ~100MB em relatórios grandes.

Fixes: #789

Exemplo 3: Refatoração

bash

refactor(service): extrai lógica de validação para classe dedicada

Validações estavam espalhadas em controllers e services.
Criada classe ValidatorService centralizando toda lógica.

Benefícios:
- Reutilização de código
- Testes mais simples
- Manutenção facilitada
- Consistência nas validações

Exemplo 4: Breaking Change

bash

feat(api)!: padroniza estrutura de resposta de todos endpoints

BREAKING CHANGE: estrutura de resposta da API foi padronizada

Antes:
GET /users → { users: [...] }
GET /equipamentos → { data: [...] }

Agora (todos endpoints):
{
  "data": [...],
  "meta": { "total": 100, "page": 1 }
}

Migração necessária em todos clientes da API.
Ver documentação completa: docs/api/migration-v2.md

Refs: #890

Exemplo 5: Com Nomes Próprios

bash

feat(auth): adiciona autenticação com Google OAuth

Implementa fluxo OAuth 2.0 para login com Google.
Utiliza biblioteca oficial do Google para Node.js.

Configuração necessária:
- Criar aplicação no Google Cloud Console
- Adicionar client_id e client_secret no .env
- Configurar redirect_uri autorizado

Refs: #445

Exemplo 6: Múltiplas Tecnologias

bash

chore(docker): atualiza stack de containers

Atualizações:
- Node: v18 → v20
- PostgreSQL: v14 → v16
- Redis: v7.0 → v7.2
- Nginx: v1.24 → v1.25

Testado em ambiente de staging sem problemas.

Ferramentas

Commitlint

Valida mensagens de commit automaticamente.

bash

# Instalação (será configurado no CI/CD)
npm install --save-dev @commitlint/cli @commitlint/config-conventional

# Configuração
echo "module.exports = {extends: ['@commitlint/config-conventional']}" > commitlint.config.js

Commitizen

Assistente interativo para criar commits.

bash

# Uso
git add .
npm run commit  # ao invés de git commit

# Irá perguntar:
# - Tipo do commit
# - Escopo
# - Descrição
# - Breaking changes

Recursos

Conventional Commits (spec oficial)
Angular Commit Guidelines - Base do nosso padrão
Semantic Versioning
Keep a Changelog

Dúvidas? Consulte este guia ou pergunte no canal #dev do Teams.

Guia Completo de Commits ​

Estrutura Detalhada ​

Componentes ​

Tipos em Detalhes ​

feat - Nova Funcionalidade ​

fix - Correção de Bug ​

docs - Documentação ​

style - Estilo e Formatação ​

refactor - Refatoração ​

perf - Performance ​

test - Testes ​

chore - Tarefas de Manutenção ​

revert - Reverter Commit ​

Escopo: Quando Usar ou Não ​

✅ Use escopo quando: ​

❌ Não use escopo quando: ​

Dica de Ouro ​

Breaking Changes - Detalhado ​

Quando é Breaking Change? ​

Formato 1: Usando ! ​

Formato 2: Usando BREAKING CHANGE: (Recomendado) ​

Múltiplos Breaking Changes ​

Corpo do Commit ​

Quando usar corpo: ​

Formatação do corpo: ​

Rodapés ​

Referência a Issues ​

Co-autoria (Pair Programming) ​

Reviewed-by ​

Múltiplos rodapés ​

Casos Especiais ​

Merge Commits ​

Work in Progress (WIP) ​

Commits de Configuração Inicial ​

Boas Práticas ​

1. Commits Atômicos ​

2. Descrição Clara e Específica ​

3. Verbo no Imperativo ​

4. Capitalização - Regras do Mercado ​

Regra Geral: Tudo Minúscula ​

Exceções: Nomes Próprios e Siglas ​

Resumo da Regra ​

Regra Prática ​

5. Sem Ponto Final ​

Erros Comuns ​

❌ Tipo em maiúscula ​

❌ Espaço entre tipo e : ​

❌ Descrição muito longa ​

❌ Commit genérico ​

❌ Misturar mudanças ​

❌ Capitalização incorreta ​

Exemplos do Mundo Real ​

Exemplo 1: Feature Completa ​

Exemplo 2: Bug Crítico ​

Exemplo 3: Refatoração ​

Exemplo 4: Breaking Change ​

Exemplo 5: Com Nomes Próprios ​

Exemplo 6: Múltiplas Tecnologias ​

Ferramentas ​

Commitlint ​

Commitizen ​

Recursos ​

Guia Completo de Commits

Estrutura Detalhada

Componentes

Tipos em Detalhes

`feat` - Nova Funcionalidade

`fix` - Correção de Bug

`docs` - Documentação

`style` - Estilo e Formatação

`refactor` - Refatoração

`perf` - Performance

`test` - Testes

`chore` - Tarefas de Manutenção

`revert` - Reverter Commit

Escopo: Quando Usar ou Não

✅ Use escopo quando:

❌ Não use escopo quando:

Dica de Ouro

Breaking Changes - Detalhado

Quando é Breaking Change?

Formato 1: Usando `!`

Formato 2: Usando `BREAKING CHANGE:` (Recomendado)

Múltiplos Breaking Changes

Corpo do Commit

Quando usar corpo:

Formatação do corpo:

Rodapés

Referência a Issues

Co-autoria (Pair Programming)

Reviewed-by

Múltiplos rodapés

Casos Especiais

Merge Commits

Work in Progress (WIP)

Commits de Configuração Inicial

Boas Práticas

1. Commits Atômicos

2. Descrição Clara e Específica

3. Verbo no Imperativo

4. Capitalização - Regras do Mercado

Regra Geral: Tudo Minúscula

Exceções: Nomes Próprios e Siglas

Resumo da Regra

Regra Prática

5. Sem Ponto Final

Erros Comuns

❌ Tipo em maiúscula

❌ Espaço entre tipo e :

❌ Descrição muito longa

❌ Commit genérico

❌ Misturar mudanças

❌ Capitalização incorreta

Exemplos do Mundo Real

Exemplo 1: Feature Completa

Exemplo 2: Bug Crítico

Exemplo 3: Refatoração

Exemplo 4: Breaking Change

Exemplo 5: Com Nomes Próprios

Exemplo 6: Múltiplas Tecnologias

Ferramentas

Commitlint

Commitizen

Recursos