Pular para o conteúdo
codigoaberto.blog

Versionamento semântico: o que MAJOR, MINOR e PATCH significam

O número da versão diz o que mudou. Veja quando cada parte sobe e as regras que mais confundem.

Quando sobe o MAJOR, o MINOR e o PATCH?

O MAJOR sobe em mudança incompatível na API pública, o MINOR em funcionalidade nova compatível e o PATCH em correção compatível de defeito. Ao subir um número, os da direita voltam a zero.

A ideia em uma frase

No versionamento semântico (SemVer), o número da versão diz o que mudou. São três números separados por pontos, MAJOR.MINOR.PATCH, e cada um sobe por um motivo diferente. Quem usa a sua biblioteca olha o número e sabe se pode atualizar sem medo ou se precisa ler as notas antes. A especificação em vigor é a 2.0.0, publicada em semver.org.

Quando cada número sobe

  • MAJOR (primeiro): quando você faz uma mudança incompatível na API pública. Quem usa a versão antiga pode ter de alterar o próprio código. Ao subir o MAJOR, MINOR e PATCH voltam a zero.
  • MINOR (segundo): quando você acrescenta uma funcionalidade compatível, ou marca algo como obsoleto. O PATCH volta a zero. A especificação admite subir o MINOR também por melhorias internas substanciais.
  • PATCH (terceiro): quando você corrige defeitos sem quebrar a compatibilidade.

Os números são inteiros não negativos, sem zeros à esquerda, e crescem numericamente: 1.9.0 vem antes de 1.10.0, porque 9 é menor que 10.

As regras que mais surpreendem

  • O software precisa ter uma API pública declarada, no código ou na documentação, e precisa ser precisa. Sem saber o que é público, ninguém sabe o que é "quebrar".
  • Uma versão lançada não muda. Qualquer correção, mesmo de uma vírgula, vira uma versão nova.
  • Versões 0.y.z são de desenvolvimento inicial. Nelas, qualquer coisa pode mudar a qualquer momento, e a API não deve ser considerada estável. A versão 1.0.0 é a que estabelece a API pública.
  • Pré-lançamentos levam um hífen e identificadores, como 1.0.0-alpha.1. A versão com hífen tem precedência menor que a versão normal: 1.0.0-alpha vem antes de 1.0.0.
  • Metadados de build vêm depois de um sinal de mais, como 1.0.0+20261011, e não entram na comparação de precedência.

SemVer e mensagens de commit

O padrão Conventional Commits foi pensado para casar com o SemVer: fix corresponde ao PATCH, feat ao MINOR e qualquer quebra de compatibilidade (o ! ou o rodapé BREAKING CHANGE) ao MAJOR. Se o seu projeto usa os dois, o histórico de commits já diz qual deve ser a próxima versão. O gerador de mensagem de commit mostra o efeito de cada mensagem no número da versão. E o número aparece, no fim, no changelog.

Exemplo resolvido: qual é a próxima versão?

A versão atual do projeto listaki é 1.4.2. Quatro mudanças diferentes:

O que mudouPróxima versãoPor quê
Corrigido o travamento com arquivo vazio1.4.3correção compatível: PATCH
Novo filtro por etiqueta, sem alterar o resto1.5.0funcionalidade compatível: MINOR, PATCH volta a zero
O comando list agora devolve JSON em vez de texto2.0.0incompatível: MAJOR, MINOR e PATCH voltam a zero
Candidata à próxima versão maior2.0.0-rc.1pré-lançamento, vale menos que 2.0.0

Repare que as duas primeiras linhas partem de 1.4.2 e a terceira também: cada linha responde "e se só esta mudança entrasse?". Se as três entrassem juntas na mesma versão, vale a mais alta: 2.0.0.

Perguntas frequentes

O que significa uma versão 0.y.z?

Segundo a especificação 2.0.0, versões com MAJOR zero são de desenvolvimento inicial: qualquer coisa pode mudar a qualquer momento, e a API não deve ser considerada estável. A versão 1.0.0 é a que estabelece a API pública.

Posso corrigir uma versão já lançada?

Não. A regra 3 diz que uma versão lançada não deve ser modificada: qualquer mudança, mesmo mínima, exige uma versão nova. Se você lançou 1.4.2 com um erro, a correção sai como 1.4.3.

Como marcar um pré-lançamento?

Com um hífen e identificadores alfanuméricos depois da versão, como 1.0.0-alpha.1. Uma versão de pré-lançamento tem precedência menor que a versão normal correspondente: 1.0.0-alpha vem antes de 1.0.0.

O sinal de mais, como em 1.0.0+build.5, muda a versão?

Não. Os metadados de build vêm depois de um sinal de mais e são ignorados na comparação de precedência, segundo a especificação. Duas versões que só diferem nos metadados têm a mesma precedência.

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.

  • 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.
  • 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.

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.