Pular para o conteúdo
codigoaberto.blog

Conventional Commits: as 16 regras explicadas

A especificação 1.0.0 resumida em português: a estrutura da mensagem, os tipos e a ligação com o versionamento semântico.

Ferramenta relacionada

Gerar e validar a mensagem

Abrir a ferramenta

O que é o Conventional Commits e como usar?

É uma especificação, na versão 1.0.0, que pede mensagens no formato tipo(escopo): descrição, com corpo e rodapés opcionais. feat corresponde ao MINOR do SemVer, fix ao PATCH e qualquer quebra de compatibilidade ao MAJOR.

O que é o Conventional Commits

É uma especificação curta, na versão 1.0.0, que dá uma estrutura à mensagem de commit. A primeira linha é tipo(escopo): descrição; depois podem vir um corpo e rodapés. Como o formato é previsível, pessoas e programas conseguem ler a mesma mensagem, e a especificação liga os tipos feat e fix aos números MINOR e PATCH do versionamento semântico. A especificação usa as palavras MUST, MAY e SHALL no sentido da RFC 2119; neste guia, "deve" é obrigatório e "pode" é opcional.

A estrutura

  • Tipo: um substantivo, como feat ou fix. É obrigatório.
  • Escopo: opcional, um substantivo entre parênteses que diz a parte do código, como fix(parser):.
  • !: opcional, logo antes dos dois-pontos, indica uma mudança que quebra compatibilidade.
  • Dois-pontos e um espaço: obrigatórios.
  • Descrição: obrigatória, logo depois, resumindo a mudança.
  • Corpo: opcional, livre, começa depois de uma linha em branco e pode ter vários parágrafos.
  • Rodapés: opcionais, depois de uma linha em branco. Cada um é um token, o separador : ou #, e um valor, como Refs: #123 ou Reviewed-by: Z. Tokens trocam espaços por hífen, com uma exceção: BREAKING CHANGE.

Quais tipos usar

A especificação define só dois tipos: feat para uma funcionalidade nova e fix para a correção de um defeito. Ela diz que outros tipos podem ser usados e dá docs como exemplo. A lista build, chore, ci, docs, style, refactor, perf e test aparece na especificação como a que o pacote @commitlint/config-conventional recomenda, baseada na convenção do Angular. Ou seja: é um costume amplo, não uma regra. Se o seu projeto usa outros tipos, tudo bem.

Ligação com o versionamento semântico

A especificação associa fix ao número PATCH e feat ao número MINOR do versionamento semântico. Qualquer mudança que quebra compatibilidade, de qualquer tipo, corresponde ao número MAJOR. Os demais tipos não alteram o número por si sós.

Quebra de compatibilidade

Há duas formas, que podem ser combinadas: o ! antes dos dois-pontos, como em feat(api)!: troca o formato da resposta, ou um rodapé BREAKING CHANGE: descrição, que deve estar em maiúsculas. Com o !, o rodapé pode ser omitido, e a descrição passa a explicar a quebra. No rodapé, BREAKING-CHANGE com hífen vale como sinônimo.

As 16 regras, resumidas

A tabela abaixo é um resumo próprio em português; o texto original, em inglês, está na página da especificação.

RegraResumo
1Começa com tipo, escopo opcional, ! opcional, dois-pontos e espaço.
2feat para funcionalidade nova.
3fix para correção de defeito.
4Escopo é um substantivo entre parênteses.
5A descrição vem logo depois de dois-pontos e espaço.
6O corpo começa uma linha em branco depois da descrição.
7O corpo é livre.
8Rodapés vêm depois de uma linha em branco: token, : ou #, valor.
9Token do rodapé usa hífen no lugar de espaço; exceção: BREAKING CHANGE.
10O valor do rodapé pode ter espaços e linhas; termina no próximo token.
11A quebra de compatibilidade vai no prefixo ou em um rodapé.
12O rodapé de quebra é BREAKING CHANGE: em maiúsculas, com descrição.
13No prefixo, o ! vem logo antes dos dois-pontos.
14Outros tipos além de feat e fix são permitidos.
15Maiúsculas e minúsculas não importam, exceto em BREAKING CHANGE.
16BREAKING-CHANGE é sinônimo de BREAKING CHANGE no rodapé.

Exemplo resolvido

Uma funcionalidade que também quebra compatibilidade, com issue relacionada:

feat(api)!: troca o formato da resposta

O campo data agora é uma lista, e não um objeto.

BREAKING CHANGE: o campo data mudou de objeto para lista
Closes #42

Pelas regras: tipo feat (regra 2), escopo api (4), ! antes dos dois-pontos (13), corpo depois de uma linha em branco (6) e dois rodapés (8 e 12). Efeito na versão: MAJOR, porque há quebra. O gerador de mensagem de commit monta esse texto a partir de um formulário, e o validador da mesma página lê uma mensagem colada e aponta a regra que ela contraria.

Perguntas frequentes

O Conventional Commits é obrigatório?

Não. É uma convenção que cada projeto decide adotar. Antes de usar em um projeto que não é seu, olhe o histórico e o CONTRIBUTING: se o projeto usa outro estilo, siga o dele.

Quais tipos existem além de feat e fix?

A especificação define só feat e fix e diz que outros tipos podem ser usados, citando docs como exemplo. A lista build, chore, ci, docs, style, refactor, perf e test aparece como a recomendada pelo @commitlint/config-conventional, baseada na convenção do Angular.

Como indico uma mudança que quebra compatibilidade?

Com um ! logo antes dos dois-pontos, como em feat(api)!: descrição, ou com um rodapé BREAKING CHANGE: descrição, em maiúsculas. Podem ser usados juntos. Com o !, o rodapé pode ser omitido.

Tipo em maiúsculas, como Feat, é válido?

Sim, pela regra 15 a especificação não diferencia maiúsculas de minúsculas, com uma exceção: BREAKING CHANGE precisa estar em maiúsculas. Quase todos os projetos escrevem o tipo em minúsculas, e o validador deste site avisa disso sem tratar como erro.

Existe a especificação em português?

Sim. A página conventionalcommits.org/pt-br/v1.0.0 traz a versão 1.0.0 em português do Brasil, com a mesma licença CC BY 3.0 no rodapé. Este guia resume as regras em texto próprio e mantém o trecho original em inglês no validador.

Fontes deste guia

Abertas em 11/10/2026. O texto é nosso, em português; as fontes ficam aqui com link, licença e o que foi lido.

  • Conventional Commits 1.0.0 (conventionalcommits.org)
    A página não mostra data · aberta em · reconferência: confirmada na abertura (11/10/2026) · licença do conteúdo: CC BY 3.0
    O que lemos: As 16 regras numeradas (tipo, escopo, ! , descrição, corpo, rodapés, BREAKING CHANGE), a ligação entre feat e fix e os números MINOR e PATCH do SemVer, a lista de tipos recomendada pelo @commitlint/config-conventional e os exemplos. A versão exibida é a 1.0.0; a página não marca nenhuma versão mais nova.
    Como usamos: As regras são resumidas em português e citadas por número. Os trechos em inglês são curtos, de regras, com a fonte ao lado.
  • Conventional Commits 1.0.0, em português do Brasil (conventionalcommits.org)
    A página não mostra data · aberta em · reconferência: confirmada na abertura (11/10/2026) · licença do conteúdo: CC BY 3.0
    O que lemos: Confirmei que existe a tradução em português do Brasil da versão 1.0.0 e que ela traz a mesma licença no rodapé.
    Como usamos: Só link, para quem prefere ler em português.
  • Versionamento Semântico 2.0.0 (semver.org)
    A página não mostra data · aberta em · reconferência: confirmada na abertura (11/10/2026) · licença do conteúdo: CC BY 3.0
    O que lemos: As 11 regras da versão 2.0.0 (API pública, X.Y.Z, versão lançada não muda, 0.y.z, pré-lançamento com hífen, metadados com +, precedência) e o resumo MAJOR, MINOR e PATCH.
    Como usamos: Resumo próprio das regras, em português, com o número da regra. O texto da especificação não é reproduzido.

Informação geral, não é aconselhamento jurídico. Quando um guia cita uma licença de conteúdo, ela vale para a página citada, não para este site.

Continue pelos guias

Os geradores, o passo a passo e os guias ficam a um clique.