Todo npm install é um ato de fé: você confia que a atualização de uma dependência não vai quebrar seu sistema. O que sustenta essa fé (quando ela se sustenta) é um contrato de três números: o versionamento semântico, ou SemVer (semver.org). Fechamos a série de versionamento com ele, porque é onde o fluxo de código encontra o mundo: versão é comunicação.

O contrato: MAJOR.MINOR.PATCH

Dado um número 2.4.1, cada posição carrega uma promessa:

• PATCH (2.4.1 → 2.4.2): correção de bug, nada muda para quem usa. Atualize sem medo.
• MINOR (2.4.1 → 2.5.0): funcionalidade nova, compatível com o que existe. Atualize quando quiser o recurso.
• MAJOR (2.4.1 → 3.0.0): quebra de compatibilidade. Algo que funcionava vai parar de funcionar; leia o guia de migração antes.

A palavra-chave do contrato inteiro: breaking change. Remover uma função, renomear um campo do retorno, mudar um default, apertar uma validação: tudo isso quebra quem depende de você, e o MAJOR é o aviso obrigatório. O ! do Conventional Commits marca exatamente esses commits, e é o elo entre as duas disciplinas: com commits tipados, a versão se calcula sozinha (semantic-release e afins): fix → patch, feat → minor, ! → major. O número deixa de ser opinião de sexta-feira.

O outro lado do balcão: consumindo versões

O package.json fala SemVer nos ranges, e entendê-los evita sustos:

{
  "dependencies": {
    "biblioteca-a": "^2.4.1",   // aceita 2.x.x (minor e patch): confia no contrato
    "biblioteca-b": "~2.4.1",   // aceita só 2.4.x (patch): mais conservador
    "biblioteca-c": "2.4.1"     // exatamente esta: máxima previsibilidade
  }
}

As três verdades práticas:

1. O lockfile é quem manda. O range declara a intenção; o package-lock.json congela a realidade. É ele que garante o build reproduzível: commite-o sempre, e instale com npm ci na esteira.
2. ^ é confiança no contrato alheio. Funciona na maioria do ecossistema maduro, e falha memorávelmente quando um autor quebra em minor. Por isso os alertas automatizados de dependência + testes na esteira são a rede: a atualização chega por PR, a suíte julga.
3. 0.x é terra sem lei declarada. Antes do 1.0.0, o contrato oficialmente não vale (qualquer minor pode quebrar). Trate dependências 0.x com ranges conservadores, e o seu próprio produto: se alguém depende dele, o 1.0.0 é menos sobre maturidade e mais sobre assumir o contrato.

SemVer além de bibliotecas

O contrato vale para tudo que tem consumidores que você não controla:

• APIs: o /v1 na URL é o MAJOR em outra roupa: quebrou o contrato, versão nova, com as duas convivendo durante a migração.
• Eventos e schemas: o schema do evento versionado evita o consumidor quebrado em silêncio.
• Imagens e artefatos: a tag imutável do container com SemVer comunica o risco do upgrade num relance.

A disciplina é uma só, em todas as roupas: mudança compatível flui; quebra se anuncia com número, changelog e caminho de migração.

Fechando a série (e o ciclo)

Fluxo de branches que casa com o ritmo de entrega, commits que contam a história, versões que comunicam o risco: as três peças do mesmo sistema de confiança. Um time que domina as três entrega rápido e sem drama, e é esse sistema completo que instalamos no serviço de DevOps e Deploy.

Sua API pública está em qual versão, e quem decidiu? Se a resposta é "está no ar desde sempre, sem número", há um contrato implícito esperando para quebrar. Converse com a IA da Rabelo Digital, aqui no canto da tela, e ela desenha o versionamento. Sem formulário, sem espera.

---

Leia também

• GitFlow vs GitHub Flow: o fluxo certo para o seu ritmo
• Commits e PRs que contam histórias