A estrutura: type(scope): descrição

Fechou o problema: agora você quer que cada commit conte uma história. O Conventional Commits organiza toda a mensagem na cabeça do commit (subject) - a primeira linha. É ela que as ferramentas leem.

O esqueleto em uma linha

O formato base é simples:

<type>(<scope>): <description>
       │        │
       │        └─ o quê (resumo em minúsculas)
       └─ categoria (onde) e impacto

Na prática:

feat(auth): adiciona login com token JWT
fix(cart): corrige cálculo de frete para múltiplos itens

Repara nos detalhes:

• type e description são obrigatórios.
• (scope) é opcional - se vier, não pode ter espaço nem estar vazio.
• Depois de type: tem exatamente uma expressão: type(scope): descrição, sem espaços antes dos dois-pontos.
• A descrição começa com verbo no imperativo, minúscula, sem ponto final.

// ✅ correto
// feat: adiciona endpoint de reset de senha

// ❌ errado
// feat :adiciona endpoint de reset de senha   (espaço antes dos dois-pontos)
// Feat: Adiciona endpoint...                  (maiúscula + verbo impessoal)

Dica: o verbo no imperativo ("adiciona", "corrige", "remove") é o mesmo jeito como o próprio Git escreve quando você faz git merge. Soa como uma ordem: este commit adiciona, este commit corrige.

O que a primeira linha precisa responder

Depois de escrever, pergunte-se: se eu ler só essa linha, eu sei o que mudou? Treine com exemplos:

• type = a categoria da mudança (vamos ver as principais já no próximo nó).
• description = o resumo do o quê (e às vezes o onde vai no escopo).
• Primeira linha = o único lugar que as ferramentas de release leem por padrão.

Dica: comece a ver o seu git log como um título de release a ser escrito. Se a primeira linha é confusa, a release toda fica confusa.

No próximo nó, vamos ver os tipos que o Conventional Commits define - e por que feat e fix são os únicos que mexem na versão.