Semantic Versioning no Node.js: major, minor e patch

Semantic Versioning no Node.js é uma convenção para comunicar o impacto de mudanças em pacotes e APIs. O formato mais conhecido usa três números: MAJOR.MINOR.PATCH.

Versionamento semântico não é apenas escolher números. Ele exige definir uma API pública, classificar mudanças, manter changelog e testar consumidores. Sem esse contrato, intervalos de dependência perdem significado e atualizações automáticas se tornam arriscadas.

Neste guia, você aprenderá versões major, minor e patch, pré-lançamentos, intervalos do npm, breaking changes, depreciação e boas práticas de release.

Formato básico

2.7.4

• 2: versão major;
• 7: versão minor;
• 4: versão patch.

Patch

Uma versão patch corrige comportamento sem alterar a API compatível:

1.4.2 → 1.4.3

Exemplos: corrigir cálculo, tratar erro já documentado, reduzir vazamento de memória ou atualizar documentação empacotada.

Minor

Uma versão minor adiciona funcionalidade compatível:

1.4.3 → 1.5.0

Exemplos: novo método opcional, novo subpath exportado ou novo parâmetro com valor padrão que preserva chamadas existentes.

Major

Uma versão major contém mudança incompatível:

1.5.0 → 2.0.0

Remover método, alterar formato de retorno, exigir nova versão de runtime ou modificar comportamento observável pode exigir major.

Defina a API pública

O campo exports ajuda a limitar entradas suportadas. Veja Package Exports no Node.js.

Sem fronteira explícita, consumidores podem depender de arquivos internos e transformar reorganizações em breaking changes.

Versões 0.x

Projetos abaixo de 1.0.0 ainda precisam de política clara. Não use a fase inicial como permissão para quebrar tudo sem comunicação.

Documente como minor e patch são interpretados durante o desenvolvimento inicial.

Pré-lançamentos

2.0.0-alpha.1
2.0.0-beta.2
2.0.0-rc.1

Pré-lançamentos permitem testes antes da versão estável. Eles possuem precedência menor que a versão final e não devem ser instalados acidentalmente por consumidores estáveis.

Metadados de build

2.0.0+build.145

Metadados após + não alteram precedência semântica. Use apenas quando ferramentas e fluxo de distribuição compreendem a informação.

Caret

"minha-lib": "^1.4.2"

Em uma major estável, o caret normalmente permite atualizações minor e patch compatíveis, sem avançar para a próxima major.

Tilde

"minha-lib": "~1.4.2"

O tilde costuma limitar atualizações à linha minor, aceitando patches posteriores.

Versão exata

"minha-lib": "1.4.2"

Mesmo com versão direta exata, dependências transitivas são controladas pelo lockfile. Veja Lockfile no Node.js.

Intervalos amplos

Evite *, latest ou intervalos sem limite em aplicações críticas. Eles aceitam mudanças não revisadas.

Breaking changes não óbvias

• alterar mensagem ou classe de erro usada por consumidores;
• mudar ordem de callbacks ou eventos;
• aumentar versão mínima do Node.js;
• remover caminho exportado;
• trocar CommonJS por ESM sem compatibilidade;
• alterar tipos TypeScript;
• mudar valores padrão;
• reduzir permissões ou formatos aceitos.

Tipos também são API

Uma alteração que compila diferente para consumidores TypeScript pode ser incompatível, mesmo quando o JavaScript em runtime continua funcionando.

Comportamento e desempenho

SemVer cobre API pública. Mudanças grandes de desempenho, consumo de memória ou timing podem exigir comunicação especial quando afetam contratos operacionais.

Depreciação

Antes de remover uma API:

1. marque como deprecated;
2. documente substituição;
3. adicione aviso controlado;
4. mantenha durante uma janela razoável;
5. remova na próxima major.

Changelog

Cada release deve explicar recursos, correções, depreciações, mudanças de segurança e instruções de migração.

Commits e automação

Convenções de commits podem automatizar releases, mas não substituem revisão humana. Um commit classificado incorretamente pode publicar versão errada.

Testes de compatibilidade

Crie projetos consumidores para versões suportadas e execute importação, tipos, chamadas públicas e cenários de migração.

Publicação

npm version patch
npm publish

O comando altera versão e pode criar commit e tag conforme configuração. Execute testes e confira o pacote antes.

npm pack --dry-run

Tags de distribuição

Pré-lançamentos devem usar tags apropriadas para não substituir a versão estável padrão:

npm publish --tag next

Monorepos

Em workspaces, pacotes podem usar versões independentes ou sincronizadas. Veja npm Workspaces no Node.js.

Versão mínima do Node.js

Alterar engines.node pode impedir instalação ou execução em consumidores. Avalie como breaking change conforme a política do pacote.

Segurança

Correções de segurança devem ser lançadas rapidamente, mas ainda precisam de versão correta, changelog e coordenação de divulgação. Evite incluir detalhes exploráveis antes de consumidores terem atualização disponível.

Erros comuns

• considerar apenas assinatura de função;
• quebrar tipos em patch;
• remover subpath em minor;
• publicar pré-release como latest;
• não manter changelog;
• usar intervalos ilimitados;
• ignorar versão mínima do runtime;
• automatizar sem revisão.

Checklist de release

• API pública definida;
• impacto classificado;
• testes completos;
• tipos validados;
• tarball conferido;
• changelog atualizado;
• migração documentada;
• tag correta;
• lockfile revisado;
• release assinada quando aplicável.

Conclusão

Semantic Versioning no Node.js cria uma linguagem comum entre mantenedores e consumidores. Patch, minor e major só têm valor quando a API pública e a política de compatibilidade são conhecidas.

Classifique mudanças pelo impacto real, incluindo tipos, runtime e comportamento. Com testes de consumo e changelog, atualizações se tornam previsíveis e automações podem operar com menos risco.

Consulte a especificação Semantic Versioning em português e a documentação do npm sobre versionamento semântico.