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 versão em contrato legível por máquina. A revisão 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 número, o consumidor sabe se a atualizacao e segura. O validador desta página checa que a string respeita a gramatica completa publicada na especificação, incluindo o identificador de pre-lançamento e a metadata de build (ambos opcionais).

A trinca MAJOR.MINOR.PATCH

Uma versão de release tem exatamente três inteiros não negativos separados por ponto, sem zeros a esquerda: 1.2.3, 0.4.17, 10.0.0. As regras de incremento são rigidas:

• MAJOR — incrementa numa mudança incompativel (breaking change) da API publica.
• MINOR — incrementa quando se adiciona funcionalidade compatível com versões anteriores.
• PATCH — incrementa apenas em correcoes de bug compatíveis.

Incrementar um componente superior zera os inferiores: 1.4.7 -> 2.0.0, nunca 2.4.7. Refatoracoes internas que não afetam a superfície publica permanecem no PATCH.

Identificadores de pre-lançamento e metadata de build

O pre-lançamento e anexado com um hífen e identificadores separados por ponto, compostos por ASCII alfanumérico 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 versão normal, e a ordem dos identificadores importa: alpha < alpha.1 < beta < rc.1 < 1.0.0.

A metadata de build vem após 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 são considerados a mesma release para resolução 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 estável e a 1.0.0, que deve sair quando a API publica for considerada pronta para produção.

Um antipattern comum e pular direto de 0.9.x para 2.0.0 sem nunca publicar 1.0.0. Alguns projetos adotam também 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, comparação e satisfacao de ranges. Os dois prefixos mais comuns:

• ^1.2.3 (caret) — release compatível: >=1.2.3 <2.0.0. Permite saltos de MINOR e PATCH.
• ~1.2.3 (til) — release próxima: >=1.2.3 <1.3.0. Permite apenas saltos de PATCH.
• >=1.0.0 <2.0.0 — range explícito, idêntico 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 versões resolvidas para que npm ci seja totalmente reproduzivel. O Yarn Plug'n'Play (PnP) leva o determinismo adiante eliminando o node_modules.

Além do npm: tags GitHub, imagens Docker e versões de API

SemVer aparece em vários outros lugares:

• Tags Git — convenção v1.2.3 nos GitHub Releases (o v não faz parte do SemVer).
• Tags Docker — node:20.11.0, com aliases móveis 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 próxima SemVer automaticamente.

Um esquema completamente diferente e o CalVer (versionamento por calendário), 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 estável?

Não. 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 produção e você assume as garantias de estabilidade do SemVer. Muitos projetos fazem o salto quando a documentação esta completa e existe pelo menos um consumidor externo.

Como são ordenados os identificadores de pre-lançamento?

Compare identificador por identificador da esquerda para a direita. Identificadores numéricos comparam numericamente; alfanuméricos comparam lexicograficamente; numérico sempre menor que alfanumérico na mesma posição; menos identificadores e menor que mais identificadores se o prefixo bater.

A metadata de build afeta a precedencia?

Não. 1.0.0+build.1 e 1.0.0+build.2 são equivalentes na resolução 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 código de aplicação com lockfile, caret e o padrão do npm e normalmente esta de bom tamanho.