Escopo e assunto: onde e o quê

Você já tem type e descrição. Mas e o escopo - aquele parênteses entre o type e os dois-pontos? Ele é opcional, então parece fácil deixar de fora. A verdade é que ele é a ferramenta mais poderosa pra organizar um repositório grande em pouco espaço.

O escopo identifica o onde

O escopo responde em que parte do sistema a mudança aconteceu. Não é uma regra de fábrica - é uma escolha que o time faz, geralmente alinhada a módulos, domínios ou pastas.

feat(auth): adiciona login com token
feat(api): cria endpoint de reset de senha
fix(cart): corrige frete para múltiplos itens
docs(readme): explica instalação

Um git log com escopo vira um mini-mapa do projeto:

# tudo que mexeu em "auth" no último mês
git log --oneline --grep="^feat(auth)"
# ou, com escopo variável, é fácil filtrar por tipo e pasta
git log --oneline --grep="feat("

Tem o ponto crucial: o escopo é livre - o conventional commits não determina quais valores usar. Então os times normalmente alinham: nomes de pasta, de módulo, ou de area funcional (auth, checkout, docs, infra). O importante é ser curto, estável e bater com o que as pessoas conhecem no repo.

⚠️  escopo vazio ou com espaço → inválido na especificação
feat( ): x        ❌ vazio
feat(auth api): x ❌ espaço no meio
feat(auth-api): x ✅ hífen ok (é um único token)

Dica: quando a mudança for grande demais pra um único escopo (ou o repo for pequeno), deixe o escopo de fora - feat: ... é perfeitamente válido. Escopo existe pra organizar, não pra burocratizar.

O assunto: uma frase imperativa e objetiva

O assunto (a parte depois de :) deve dizer o quê o commit faz. Em vez de descrever o passado ("adicionei...") ou o desejo ("deveria..."), descreva a ação que o commit executa - verbo no imperativo.

// ✅ imperativo, curto
// feat: adiciona endpoint de reset de senha
// ❌ passado / vago
// feat: added endpoint
// feat: melhorias gerais

Regras rápidas do assunto:

• comece com verbo no imperativo (adiciona, corrige, remove, atualiza);
• minúscula (não "Adiciona", a menos que seja um acrônimo como JWT);
• sem ponto final no fim;
• resume um conceito - o assunto é um resumo, não o changelog inteiro.

// bom: uma mudança, uma ideia
// feat(checkout): adiciona aplicação de cupom
// não: empilha várias coisas
// feat: adiciona cupom, corrige frete e atualiza README

• escopo identifica o onde (módulo/pasta); assunto o o quê.
• escopo é opcional, curto, sem espaço; escolha valores alinhados com o time.
• assunto: verbo no imperativo, minúscula, sem ponto, uma ideia por commit.

Dica: um bom teste é tentar resumir o commit numa frase falada: "este commit adiciona X". Se a frase soa estranha, ajuste o verbo.

No próximo nó, vamos ver corpo e rodapé - onde mora o porquê e a marca de quebra (BREAKING CHANGE).