Calculadora SemVer — Ferramenta Online Grátis

Calcule incrementos de versão semântica e valide a compatibilidade de ranges de versão do npm instantaneamente.

Calculadora de Incremento de Versão

Major
1.0.0 → 2.0.0
Breaking changes. Incompatibilidade de API.
Minor
1.4.0 → 1.5.0
Novas funcionalidades, retrocompatível.
Patch
1.4.2 → 1.4.3
Correções de bugs, sem novas funcionalidades.

Verificador de Range de Versão

Ranges comuns:
^1.0.0 ~1.4.2 >=1.0.0 <2.0.0 1.x * (qualquer)

Histórico de Versões — Simular Incrementos

O que é Versionamento Semântico?

O Versionamento Semântico (SemVer) é uma especificação de versionamento que usa um formato de três números: MAJOR.MINOR.PATCH (ex: 2.4.1). Ele fornece uma maneira padronizada de comunicar a natureza das alterações em cada release, ajudando os desenvolvedores a entender o que esperar ao atualizar uma dependência.

A especificação SemVer (semver.org) define regras claras: incremente MAJOR para breaking changes, MINOR para novas funcionalidades retrocompatíveis e PATCH para correções de bugs retrocompatíveis.

Quando Incrementar Cada Parte da Versão

  • MAJOR (breaking change): Removeu um método público da API, alterou assinaturas de funções, descontinuou e removeu comportamento antigo, alterou o fluxo de autenticação.
  • MINOR (nova funcionalidade): Adicionou um novo endpoint, adicionou parâmetros opcionais a funções existentes, adicionou novas opções de configuração.
  • PATCH (correção de bug): Corrigiu um crash, corrigiu comportamento incorreto, melhoria de performance sem alteração na API, correção de documentação.

Sintaxe de Range de Versão do npm

  • ^1.2.3 — Compatível com 1.2.3. Permite atualizações MINOR e PATCH (>=1.2.3 <2.0.0)
  • ~1.2.3 — Aproximadamente equivalente. Permite apenas atualizações PATCH (>=1.2.3 <1.3.0)
  • >=1.2.3 <2.0.0 — Range explícito, intenção muito clara
  • 1.x — Qualquer versão com major 1
  • * — Qualquer versão (perigoso para produção)
  • 1.2.3 — Versão exata apenas (sem atualizações)

Versionamento Semântico na Prática: Além da Teoria

O Versionamento Semântico (SemVer) fornece um contrato claro entre autores de bibliotecas e consumidores sobre quais mudanças esperar em cada release. No entanto, decisões de versionamento no mundo real são mais nuanceadas que a simples fórmula MAJOR.MINOR.PATCH.

Quando Incrementar Cada Número de Versão

  • MAJOR (mudanças incompatíveis): Remover uma API pública, alterar uma assinatura de função, renomear módulos exportados, descontinuar suporte a uma versão de runtime, ou alterar comportamento padrão do qual usuários existentes dependem.
  • MINOR (novas funcionalidades, compatível): Adicionar novas funções, endpoints ou opções. Adicionar parâmetros opcionais a funções existentes. Deprecar (mas não remover) APIs existentes.
  • PATCH (apenas correções): Corrigir comportamento incorreto, patches de segurança, melhorias de performance que não alteram a API, correções de documentação.

Estratégias de Faixa de Versão para package.json

  • ^1.2.3 (caret — padrão do npm): Permite atualizações MINOR e PATCH: ≥1.2.3 <2.0.0. Melhor para a maioria das dependências.
  • ~1.2.3 (til): Permite apenas atualizações PATCH: ≥1.2.3 <1.3.0. Mais conservador.
  • 1.2.3 (exato): Trava exatamente nesta versão. Mais conservador — use para dependências críticas onde qualquer mudança é arriscada.

Versões Pré-release e Metadados de Build

SemVer suporta identificadores pré-release (1.0.0-alpha.1, 2.0.0-beta.3, 1.0.0-rc.1). Versões pré-release têm menor precedência que a versão release: 1.0.0-alpha < 1.0.0. Metadados de build (1.0.0+20260314) são ignorados em comparações de precedência mas úteis para rastrear informação de build.

Perguntas Frequentes sobre Versionamento Semântico

Qual é a diferença entre ^1.0.0 e ~1.0.0 no npm?

O circunflexo (^) permite atualizações compatíveis dentro da mesma versão major: ^1.0.0 aceita qualquer versão >=1.0.0 e <2.0.0, permitindo atualizações minor e patch. O til (~) é mais restritivo: ~1.0.0 aceita apenas atualizações patch, correspondendo a >=1.0.0 e <1.1.0. O npm usa o circunflexo (^) como padrão. Use til quando precisar de controle mais rígido sobre quais versões são instaladas.

Quando devo incrementar o número da versão major?

Incremente o major (ex: 1.x.x para 2.0.0) apenas para breaking changes que não são retrocompatíveis com a versão anterior. Isso inclui: remover ou renomear um método público da API, alterar a assinatura de parâmetros de uma função, descontinuar o suporte a um runtime ou ambiente anteriormente suportado, ou alterar o comportamento padrão quebrando integrações existentes. Adições não destrutivas sempre vão para minor, e correções de bugs sempre vão para patch.

O que significa um número de versão começando com 0?

Versões começando com 0 (ex: 0.x.x) sinalizam que o software está em desenvolvimento inicial e a API pública ainda não é estável. Sob o SemVer, qualquer coisa pode mudar a qualquer momento durante o desenvolvimento 0.x — incluindo breaking changes com incrementos minor (0.1.0 para 0.2.0). Incremente para 1.0.0 apenas quando estiver pronto para se comprometer com uma API pública estável e documentada que você manterá com retrocompatibilidade.

Como lançar uma versão prerelease usando SemVer?

Adicione um identificador prerelease após um hífen: 1.0.0-alpha.1, 1.0.0-beta.2, 1.0.0-rc.1. Versões prerelease têm precedência menor que a release: 1.0.0-alpha < 1.0.0-beta < 1.0.0-rc.1 < 1.0.0. No npm, publique prereleases com npm publish --tag next para que não sejam instaladas por padrão. Os seletores de range caret e tilde não correspondem automaticamente a versões prerelease.

Ferramentas Relacionadas