Conventional Commits

Scope (opcional mas recomendado)

• Lowercase, específico ao componente/módulo/área
• Exemplos: api, parser, auth, database, ui, config

Descrição (SEMPRE em Português BR)

• Imperativo presente: "adiciona" (não "adicionado" nem "adicionando")
• Sem capitalizar primeira letra
• Sem ponto (.) no final
• Max 72 caracteres (ideal < 50)
• Ser claro e conciso sobre O QUÊ mudou

Body (opcional, em Português BR)

• Separar da descrição com linha em branco
• Imperativo presente
• Explicar O QUÊ e POR QUÊ, não COMO
• Wrap em 72 caracteres
• Pode ter múltiplos parágrafos

Footer (opcional)

• BREAKING CHANGE: <descrição> para breaking changes
• Fixes #123 para fechar issues
• Refs #456 para issues relacionadas
• Reviewed-by: Name para revisores
• Múltiplos footers são permitidos

Breaking Changes

• Indicar com BREAKING CHANGE: no footer, OU
• Com ! após type/scope: feat(api)!: remove endpoints deprecados
• Deve incluir descrição da breaking change

Granularidade (REGRA CRÍTICA)

Mesmo dentro da MESMA feature, dividir commits por camada/responsabilidade.

Ordem de commits (de baixo para cima da stack):

1. Constants/Config — novas opções, configurações, valores iniciais
2. Validations — schema validations, form validations
3. Hooks/Context — state management, custom hooks, context changes
4. Components — componentes de UI que usam o acima
5. Styles — CSS/SCSS changes

Exemplo — adicionando novo tipo de relacionamento:

Em vez de UM commit grande, criar:

feat(constants): adiciona novos tipos de relacionamento nas opções
feat(constants): adiciona documentos para novos relacionamentos
feat(validation): adiciona validações para documentos de novos relacionamentos
feat(hooks): ajusta hooks para suportar novos relacionamentos
feat(components): implementa UI para novos tipos de relacionamento
style(ui): ajusta estilos de campos desabilitados

Por que isso importa:

• Easier code review (reviewer foca em uma camada por vez)
• Easier to revert mudanças específicas sem afetar outras
• Melhor documentação do que mudou e por quê
• Segue o princípio "one commit = one logical change"

Regra de ouro: Se o commit pode ser descrito com "E" (ex: "adiciona opções E validações E componentes"), são commits SEPARADOS.

Exemplos

Feature simples:

feat(auth): adiciona suporte a login OAuth2

Bug com scope:

fix(parser): corrige tratamento de valores nulos no JSON

Breaking change:

feat(api)!: remove endpoints deprecados

BREAKING CHANGE: endpoint /v1/users foi removido, use /v2/users

Com body e footer:

refactor(database): migra de MongoDB para PostgreSQL

Atualiza queries ORM e lógica de conexão para usar PostgreSQL.
Melhora performance de queries e adiciona suporte a transações.

Refs #234

Mais exemplos: