O que querem dizer os três números da versão de um pacote

Você abre o arquivo de dependências e vê "express": "^4.21.2". Três números, um acento circunflexo, e uma promessa escondida neles. Essa promessa tem nome, Versionamento Semântico, ou SemVer, e uma especificação curta, com versão oficial em português.

Entender a regra muda duas coisas no dia a dia: você sabe o que esperar de uma atualização antes de rodar, e numera os seus próprios projetos de um jeito que os outros entendem.

O que cada número significa?

O formato é MAIOR.MENOR.CORREÇÃO, como em 2.4.1. Cada número sobe por um motivo:

• Maior (o 2): mudou algo que quebra quem usa a biblioteca, uma função que sumiu ou mudou de comportamento;
• Menor (o 4): entrou funcionalidade nova, sem quebrar o que existia, ou algo foi marcado como descontinuado;
• Correção (o 1): consertaram um defeito, sem mudar o que já funcionava.

Os três são inteiros sem zero à esquerda: 2.04.1 não é uma versão válida.

Quando um número sobe, os da direita voltam a zero. Depois da 2.4.1, uma funcionalidade nova leva à 2.5.0, e uma mudança incompatível, à 3.0.0.

Por que a versão 0.x é diferente?

Porque ela não promete nada. Enquanto o número maior é zero, a especificação diz que qualquer coisa pode mudar a qualquer momento, e a API pública não deve ser considerada estável. Uma biblioteca na 0.8 pode quebrar tudo na 0.9 sem violar regra nenhuma.

A 1.0.0 é o momento em que o projeto declara a API pública. O próprio FAQ do SemVer sugere chegar nela quando o software já está em produção ou quando outras pessoas dependem dele.

E o que são o -beta e o +build?

O hífen marca uma versão de pré-lançamento, como 2.0.0-beta.1 ou 2.0.0-rc.1. Ela é considerada instável, e vem antes da versão final na ordem: 2.0.0-rc.1 é menor que 2.0.0.

Entre pré-lançamentos, a comparação vai pedaço por pedaço, e a especificação dá a ordem completa como exemplo: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-alpha.beta, 1.0.0-beta, 1.0.0-beta.2, 1.0.0-beta.11, 1.0.0-rc.1 e, por fim, 1.0.0. Repare que beta.11 vem depois de beta.2: números são comparados como números, e não como texto.

O sinal de mais carrega metadados de compilação, como 1.0.0+20261018. Eles são ignorados na comparação: duas versões que diferem só no que vem depois do mais têm a mesma precedência.

Como ler o ^ e o ~ do package.json?

Esses símbolos não são do SemVer, e sim do npm, que usa a regra para decidir o que pode atualizar sozinho. O circunflexo (^4.21.2) aceita qualquer versão até a próxima maior: 4.22.0 entra, 5.0.0 não. O til (~4.21.2) é mais conservador e aceita só correções: 4.21.9 entra, 4.22.0 não.

Repare que o circunflexo confia que a biblioteca segue o SemVer à risca. Quando ela não segue e solta uma mudança incompatível numa versão menor, o seu projeto quebra numa atualização que parecia segura. É para isso que existe o arquivo de trava (package-lock.json): ele grava a versão exata instalada, e quem clona o projeto recebe a mesma.

Vale seguir o SemVer nos meus projetos?

Em qualquer coisa que outra pessoa vai instalar, sim. Em aplicação final, que ninguém importa como dependência, a regra serve menos, e muita equipe numera por data. A leitura do Setup do Dev: se existe a chance de alguém escrever o nome do seu pacote num arquivo de dependências, siga o SemVer desde a 0.1.0. Mudar o jeito de numerar depois é mais difícil que começar certo.

Fonte: Versionamento Semântico 2.0.0

Produzido com auxílio de IA e revisado pela redação.