Versionamento Semântico: O Que 2.1.0 Realmente Significa

Semver: Um Contrato Entre Você e Seus Usuários

Versionamento Semântico (semver) é um esquema de versionamento que comunica a natureza das mudanças. Quando você vê 2.1.0 → 2.2.0, sabe que é uma adição compatível. Quando vê 2.1.0 → 3.0.0, sabe que algo quebrou.

O Formato: MAJOR.MINOR.PATCH

Componente	Quando Incrementar	Exemplo
MAJOR	Breaking changes — API incompatível com versão anterior	1.0.0 → 2.0.0
MINOR	Novas features — adições compatíveis	1.0.0 → 1.1.0
PATCH	Bug fixes — correções compatíveis	1.0.0 → 1.0.1

O Que Conta Como Breaking Change?

Remover uma função ou método público
Mudar parâmetros de função (remover, reordenar, mudar tipos)
Mudar tipos de retorno
Mudar comportamento padrão
Deixar de suportar um runtime (Node 18 → Node 20 mínimo)
Renomear módulos exportados

Ranges de Versão no package.json

{
  "dependencies": {
    "exato":     "1.2.3",       // Apenas 1.2.3
    "caret":     "^1.2.3",      // >=1.2.3 <2.0.0 (mais comum)
    "tilde":     "~1.2.3",      // >=1.2.3 <1.3.0
    "wildcard":  "1.x"           // >=1.0.0 <2.0.0
  }
}

Range	Instala	Nível de Risco
`^1.2.3`	1.2.3 até 1.x.x	Baixo — sem breaking dentro do major
`~1.2.3`	1.2.3 até 1.2.x	Muito baixo — apenas patches
`1.2.3`	Exatamente 1.2.3	Nenhum — mas sem updates de segurança

Versões Pre-release

1.0.0-alpha.1    // Desenvolvimento inicial, instável
1.0.0-beta.1     // Feature-complete, pode ter bugs
1.0.0-rc.1       // Release candidate, pronto para testes
1.0.0            // Release estável

Regras Práticas

Comece em 0.1.0 para projetos novos. Antes do 1.0.0, qualquer coisa pode mudar.
Lance 1.0.0 quando sua API é usada em produção por outros.
Use ^ (caret) no package.json — é o padrão e correto para a maioria.
Use lockfiles para fixar versões exatas em produção.
Automatize com conventional commits + semantic-release ou changesets.

Parse versões: Formatador JSON — valide e formate seu package.json.