Gerador de Conventional Commit

Conventional Commits: um contrato para o histórico

A especificação Conventional Commits (v1.0.0, em conventionalcommits.org) é uma convenção leve sobre mensagens de commit nascida por volta de 2017 dentro do time do Angular e depois extraída como spec independente. O objetivo é transformar o histórico em um documento legível por máquinas, para que ferramentas derivem o salto de versão segundo o SemVer, gerem changelog e disparem releases automaticamente — sem ninguém editar número de versão à mão.

O formato é fixo: <tipo>[escopo opcional]: <descrição> na primeira linha, um body opcional separado por linha em branco e um footer opcional. O escopo fica entre parênteses logo após o tipo para indicar a área afetada, por exemplo feat(auth): adiciona fluxo OAuth. Um breaking change é sinalizado com ! após o tipo/escopo ou com o token BREAKING CHANGE: no footer.

feat(api): adiciona cursor de paginação

Retorna um cursor base64 no header Link.
Clientes devem parar de depender de offset.

BREAKING CHANGE: parâmetro offset removido
Refs: #482

O vocabulário padrão de tipos

• feat — nova funcionalidade visível ao usuário (sobe MINOR).
• fix — correção de bug visível ao usuário (sobe PATCH).
• docs — mudanças apenas na documentação.
• style — formatação, espaços, ponto e vírgula — sem mudar comportamento.
• refactor — mudança interna que não é feature nem fix.
• perf — melhoria de performance.
• test — adicionar ou ajustar testes.
• build, ci, chore, revert — ferramental, pipeline, manutenção e reversões (em geral fora do changelog).

Integração com SemVer e release automatizado

Conventional Commits foi desenhado para alimentar o SemVer: um release com pelo menos um feat: vira MINOR, com apenas fix: vira PATCH, e qualquer commit marcado como breaking força MAJOR. Ferramentas como semantic-release, release-please (Google), standard-version e conventional-changelog leem o log, calculam a próxima versão, criam a tag e publicam um CHANGELOG.md agrupado por tipo.

Linting e ferramentas de autoria

commitlint valida o formato localmente via hook commit-msg do Husky, bloqueando mensagens malformadas antes de chegarem ao remoto. O Commitizen (cz) substitui o git commit por um prompt interativo que conduz o autor por tipo, escopo, descrição e flag de breaking change. Como alternativa estética, o gitmoji usa emojis (:sparkles:, :bug:) — é popular, mas mais difícil de automatizar.

Pegadinhas de estilo

Por convenção, a descrição é escrita no imperativo ("adicionar", não "adicionado" nem "adiciona"), começa em letra minúscula e não termina em ponto. O escopo, quando presente, não tem espaço e usa kebab-case. Parágrafos do body são separados por linha em branco e podem incluir bullets. O footer segue o formato Token: valor de git trailers (Refs:, Reviewed-by:, Closes:).

Perguntas frequentes

Como reverto um commit corretamente? Use o tipo revert: e referencie o hash original no body, ex.: revert: feat(api): adiciona cursor de paginação. As ferramentas de release reconhecem e removem a entrada do próximo changelog.

Funciona em monorepo e microsserviços? Sim — use o escopo para identificar o pacote ou serviço (feat(billing-api):). Nx, Lerna e release-please suportam versionamento por pacote derivado do escopo.

A convenção é rígida demais para times pequenos? Se os tipos estritos pesam, dá para escolher um subconjunto menor (apenas feat, fix, chore) ou migrar para gitmoji. O custo só vale a pena quando há automação real adiante.

Onde entram convenções antigas como [FEATURE] ou [BUG]? Predam Conventional Commits e expressam a mesma intenção de forma informal. Migrar é quase só um search-and-replace, mas o ganho real está em plugar commitlint e uma ferramenta de release — sem isso, o prefixo sozinho adiciona pouco.