Analisador e comparador SemVer

O que é um analisador de versões semânticas?#

Versionamento Semântico (SemVer) é a convenção maior.menor.patch que a maioria das bibliotecas usa para sinalizar que tipo de mudança um lançamento contém: uma correção de bug sobe patch, adições compatíveis com versões anteriores sobem menor, e mudanças que partem compatibilidade sobem maior. Adicione uma etiqueta de pré-lançamento (1.0.0-beta.1) ou metadados de build (+exp.sha.1) e obtém-se a gramática completa definida em semver.org 2.0.0.

O problema é que “comparar duas versões” e “esta versão satisfaz o meu intervalo de dependência” são fáceis de errar a olho. 1.0.0 é maior ou menor que 1.0.0-beta? (Maior — um lançamento supera sempre o seu pré-lançamento.) 1.2.3 satisfaz ^1.2.0? (Sim.) Satisfaz ~1.2.0? (Também sim, mas por uma razão mais restrita.) Esta página analisa versões como a spec as define, mostra-lhe os componentes, compara duas versões por precedência, e responde a consultas de intervalo com a mesma sintaxe ^ / ~ / >= / || / hífen que um package.json usa — tudo localmente, contra as regras reais em vez de um palpite.

Como usar#

1. Use os botões de preenchimento rápido no topo para largar exemplos comuns, ou escreva diretamente.
2. Introduza a Versão A e a Versão B nas duas entradas. Um v ou = inicial é aceite e retirado; 1.2.3-beta.1+build.42 é analisado nas suas partes.
3. Introduza uma expressão de Intervalo se quer uma verificação de satisfação. O padrão é ^1.2.0 || >=2.0.0 <3.0.0 — dois conjuntos em OU, como intervalos reais de dependência são escritos. Sintaxe suportada: ^ (acento circunflexo), ~ (til), >= <= > < =, wildcards x / X / *, versões parciais (1.2), intervalos de hífen -, e || para conjuntos em OU.
4. Leia os dois cartões de análise. Cada um mostra a forma canónica clean e os campos destacados maior, menor, patch, pré-lançamento e build. Uma versão inválida torna o seu cartão vermelho com uma mensagem.
5. Leia o cartão de comparação. Expõe A < B, A = B, ou A > B por precedência, mais a alteração — o componente mais alto que mudou (maior, menor, patch, pré-lançamento ou build).
6. Leia o cartão de verificação de intervalo. Diz-lhe, para o intervalo que escreveu, se A satisfaz e se B satisfaz.

Principais recursos#

• Precedência pela spec. A comparação percorre maior.menor.patch e depois os identificadores de pré-lançamento, com a regra de que uma versão sem pré-lançamento supera sempre uma com pré-lançamento. Identificadores numéricos comparam numericamente (beta.2 < beta.11); alfanuméricos comparam lexicamente; e numérico fica sempre abaixo de alfanumérico. Metadados de build são analisados e exibidos mas nunca afetam a precedência.
• Acento circunflexo e til, dessacarificados corretamente. ^1.2.3 passa a >=1.2.3 <2.0.0; ^0.2.3 passa a >=0.2.3 <0.3.0; ^0.0.3 passa a >=0.0.3 <0.0.4 — a regra do “não-zero mais à esquerda” do acento. O til fixa o mesmo menor: ~1.2.3 é >=1.2.3 <1.3.0.
• Intervalos com ||, hífens e wildcards. ^1.0.0 || >=2.0.0 <3.0.0 (OU de dois conjuntos), 1.2.0 - 1.5.0 (intervalo de hífen inclusivo), 1.x / 1.2.* (intervalos wildcard) todos analisam e testam.
• O portão de inclusão de pré-lançamento. Uma versão de pré-lançamento só pode satisfazer um intervalo quando algum comparador no mesmo conjunto transporta uma etiqueta de pré-lançamento no mesmo maior.menor.patch. Por isso 1.5.0-rc.1 não satisfaz ^1.2.0, mas satisfaz ^1.5.0-rc.0 — correspondendo a como gestores de pacotes reais mantêm pré-lançamentos aleatórios fora das builds de lançamento.
• Alteração que conta uma história. O campo de alteração reporta o componente mais alto que mudou, pelo que um salto de 1.2.3 para 2.0.0 mostra maior, e 1.0.0 para 1.0.0 com um build mudado mostra build embora a precedência esteja inalterada.
• Entrada tolerante. v inicial, um = inicial, e espaço em branco envolvente são tolerados, pelo que versões copiadas de uma tag git ou de um changelog são analisadas sem limpeza manual.

Exemplo detalhado#

Com os padrões — A 1.2.3, B 2.0.0, intervalo ^1.2.0 || >=2.0.0 <3.0.0 — a página reporta:

A clean    1.2.3        (major 1, minor 2, patch 3)
B clean    2.0.0        (major 2, minor 0, patch 0)
compare    1.2.3  <  2.0.0
diff       maior
range      A satisfaz   B satisfaz

Ambas as versões satisfazem o intervalo, mas por razões diferentes: A cai dentro do primeiro conjunto OU (^1.2.0 → >=1.2.0 <2.0.0), B cai dentro do segundo (>=2.0.0 <3.0.0). Mude B para 3.0.0 e o seu emblema passa a não satisfaz — o limite superior <3.0.0 exclui-o.

Para ver a regra de pré-lançamento em ação, defina A para 1.5.0-rc.1 e B para 1.5.0, e mantenha o intervalo como ^1.5.0-rc.0. Agora A satisfaz (mesmo 1.5.0, o intervalo transporta uma etiqueta de pré-lançamento correspondente), enquanto um ^1.5.0 simples não deixaria 1.5.0-rc.1 passar — o portão existe precisamente para manter candidatos a lançamento fora da resolução de dependências de lançamento até que se opte por eles.

Perguntas frequentes#

1.0.0 é maior do que 1.0.0-beta?#

Sim. Uma versão sem etiqueta de pré-lançamento tem sempre precedência mais alta do que uma com etiqueta de pré-lançamento, mesmo no mesmo maior.menor.patch. Por isso 1.0.0 > 1.0.0-rc.1 > 1.0.0-beta.11 > 1.0.0-alpha. É por isso que um lançamento “ir a gold” é um verdadeiro salto de precedência, não apenas uma mudança de etiqueta.

Qual é a diferença entre ^ e ~?#

O acento circunflexo permite atualizações que não modificam o componente não-zero mais à esquerda: ^1.2.3 permite qualquer 1.x.x desde 1.2.3 até (mas não incluindo) 2.0.0. O til é mais restrito — fixa o menor quando recebe uma versão completa: ~1.2.3 permite apenas 1.2.x. Dado apenas o maior (~1), til e acento permitem ambos toda a gama maior. A maioria das bibliotecas fixa com ^; correções aos seus próprios pacotes publicados usam muitas vezes ~.

Porque é que a minha versão de pré-lançamento não satisfaz ^1.0.0?#

Por desenho. Um pré-lançamento como 1.5.0-rc.1 só satisfaz um intervalo quando algum comparador no mesmo conjunto E tem uma etiqueta de pré-lançamento no mesmo 1.5.0. ^1.0.0 dessacarifica para >=1.0.0 <2.0.0-0 sem pré-lançamento em 1.5.0, pelo que o portão impede a sua build de lançamento de puxar um release candidate aleatório de alguém. Se quer optar por entrar, escreva ^1.5.0-rc.0 explicitamente.

Metadados de build afetam a comparação?#

Não. 1.0.0+exp.sha.5 e 1.0.0+exp.sha.6 têm precedência igual — metadados de build servem apenas para identificação. O analisador ainda os mostra (e a alteração reporta uma mudança build quando apenas os metadados diferem), mas nunca decide uma ordenação.