Validador de SemVer

SemVer 2.0.0: um contrato entre quem publica e quem consome biblioteca

O Versionamento Semantico, codificado em semver.org por Tom Preston-Werner (co-fundador do GitHub), transforma uma string de versao em contrato legivel por maquina. A revisao atual e a SemVer 2.0.0, e praticamente todo registro moderno de pacotes — npm, Cargo, RubyGems, Packagist, Composer, NuGet, Go modules — depende dela para resolver dependencias.

A promessa e simples: pelo numero, o consumidor sabe se a atualizacao e segura. O validador desta pagina checa que a string respeita a gramatica completa publicada na especificacao, incluindo o identificador de pre-lancamento e a metadata de build (ambos opcionais).

A trinca MAJOR.MINOR.PATCH

Uma versao de release tem exatamente tres inteiros nao negativos separados por ponto, sem zeros a esquerda: 1.2.3, 0.4.17, 10.0.0. As regras de incremento sao rigidas:

• MAJOR — incrementa numa mudanca incompativel (breaking change) da API publica.
• MINOR — incrementa quando se adiciona funcionalidade compativel com versoes anteriores.
• PATCH — incrementa apenas em correcoes de bug compativeis.

Incrementar um componente superior zera os inferiores: 1.4.7 -> 2.0.0, nunca 2.4.7. Refatoracoes internas que nao afetam a superficie publica permanecem no PATCH.

Identificadores de pre-lancamento e metadata de build

O pre-lancamento e anexado com um hifen e identificadores separados por ponto, compostos por ASCII alfanumerico e hifens: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-beta.2, 1.0.0-rc.1. Pre-lancamentos ficam abaixo da versao normal, e a ordem dos identificadores importa: alpha < alpha.1 < beta < rc.1 < 1.0.0.

A metadata de build vem apos um sinal de mais e e ignorada na precedencia: 1.0.0+20240501, 1.0.0-beta+exp.sha.5114f85. Dois builds que diferem apenas na metadata sao considerados a mesma release para resolucao de dependencias.

1.0.0-alpha    < 1.0.0-alpha.1
1.0.0-alpha.1  < 1.0.0-beta
1.0.0-beta     < 1.0.0-rc.1
1.0.0-rc.1     < 1.0.0
1.0.0          == 1.0.0+build.42

Fase 0.x.x: tudo pode mudar

Durante o desenvolvimento inicial com MAJOR 0, a API e explicitamente instavel: a spec diz "qualquer coisa PODE mudar a qualquer momento". Muitas bibliotecas permanecem nessa fase por anos para sinalizar status experimental. A primeira release estavel e a 1.0.0, que deve sair quando a API publica for considerada pronta para producao.

Um antipattern comum e pular direto de 0.9.x para 2.0.0 sem nunca publicar 1.0.0. Alguns projetos adotam tambem esquemas de brincadeira como "0ver" (sentimentalversioning.org), em que o major jamais chega a 1 — divertido, mas inutil para resolvedores automatizados de dependencias.

Sintaxe de ranges no npm: caret, til e ranges explicitos

SemVer aparece mais visivelmente dentro do package.json. A biblioteca node-semver implementa parse, comparacao e satisfacao de ranges. Os dois prefixos mais comuns:

• ^1.2.3 (caret) — release compativel: >=1.2.3 <2.0.0. Permite saltos de MINOR e PATCH.
• ~1.2.3 (til) — release proxima: >=1.2.3 <1.3.0. Permite apenas saltos de PATCH.
• >=1.0.0 <2.0.0 — range explicito, identico ao caret para major > 0.
• 1.2.x ou 1.2.* — equivalente ao til.

Para caret com MAJOR 0 o comportamento muda: ^0.2.3 resolve para >=0.2.3 <0.3.0 porque minors pre-1.0 podem quebrar. O lockfile (package-lock.json, yarn.lock, pnpm-lock.yaml) fixa as versoes resolvidas para que npm ci seja totalmente reproduzivel. O Yarn Plug'n'Play (PnP) leva o determinismo adiante eliminando o node_modules.

Alem do npm: tags GitHub, imagens Docker e versoes de API

SemVer aparece em varios outros lugares:

• Tags Git — convencao v1.2.3 nos GitHub Releases (o v nao faz parte do SemVer).
• Tags Docker — node:20.11.0, com aliases moveis node:20 e node:latest.
• APIs HTTP — normalmente so o MAJOR vai no prefixo da URL (/v1/, /v2/) ou em um header customizado. Internamente o time pode continuar contabilizando MINOR/PATCH.
• Conventional Commits — ferramentas como semantic-release e release-please leem mensagens de commit (feat:, fix:, BREAKING CHANGE:) para calcular a proxima SemVer automaticamente.

Um esquema completamente diferente e o CalVer (versionamento por calendario), usado pelo Ubuntu (24.04), pip e Black. CalVer troca o sinal de breaking change por cadencia previsivel — escolha SemVer para bibliotecas e CalVer para produtos com release baseado em tempo.

FAQ

Uma release 0.x.x e considerada estavel?

Nao. A spec reserva o MAJOR 0 para desenvolvimento inicial e permite explicitamente breaking changes a cada MINOR. Lance a 1.0.0 quando a API publica estiver travada.

Quando devo passar de 0.x para 1.0?

Quando a API ja esta sendo usada em producao e voce assume as garantias de estabilidade do SemVer. Muitos projetos fazem o salto quando a documentacao esta completa e existe pelo menos um consumidor externo.

Como sao ordenados os identificadores de pre-lancamento?

Compare identificador por identificador da esquerda para a direita. Identificadores numericos comparam numericamente; alfanumericos comparam lexicograficamente; numerico sempre menor que alfanumerico na mesma posicao; menos identificadores e menor que mais identificadores se o prefixo bater.

A metadata de build afeta a precedencia?

Nao. 1.0.0+build.1 e 1.0.0+build.2 sao equivalentes na resolucao de dependencias. Use metadata so para rastreabilidade (SHA do commit, id de build de CI etc.).

Caret ou til — qual e mais seguro?

Til e mais conservador (so PATCH) e minimiza surpresa. Caret e mais permissivo e assume que o mantenedor respeita SemVer. Para codigo de aplicacao com lockfile, caret e o padrao do npm e normalmente esta de bom tamanho.