Versão e compatibilidade

Semver na prática: o que cada número promete, como o resolvedor lê a faixa, e por que conflito é erro.

A versão de uma biblioteca é uma promessa legível por máquina. Ela responde a uma pergunta só: posso atualizar sem ler o changelog?

1.4.2
│ │ └── correção   — consertou algo, sem mudar o contrato
│ └──── menor      — acrescentou algo, sem quebrar o que havia
└────── maior      — quebrou alguma coisa

O que cabe em cada número#

A faixa, do lado de quem depende#

[dependencies]
validador = "^1.2.0"      # >=1.2.0 e <2.0.0   — aceita correção e menor
tabela    = "~1.2.0"      # >=1.2.0 e <1.3.0   — só correção
datas     = "1.2.3"       # exatamente essa
cofre     = ">=1.0 <3.0"  # comparadores, combináveis
texto     = "*"           # qualquer uma

^ é o padrão razoável: ele confia no semver de quem publicou. ~ é para quando essa confiança ainda não existe, e a versão exata é para quando existe um motivo escrito.

Antes de 1.0.0#

Enquanto o maior é 0, o contrato ainda está sendo decidido, e a convenção é que o menor carrega as quebras: 0.3.0 pode quebrar 0.2.0. Publicar 1.0.0 é a declaração de que o contrato está de pé — e é a partir dali que ele custa caro para mudar.

Conflito é erro, e não aviso#

Se dois pacotes pedem faixas incompatíveis do mesmo terceiro, dataforge install falha, dizendo quem pediu o quê. A alternativa — instalar duas cópias em versões diferentes — produz o pior tipo de bug: dois record com o mesmo nome e campos distintos circulando no mesmo programa, e um with que recusa o próprio resultado.

O lockfile#

O lock é o que faz a instalação de hoje ser igual à de três meses atrás — e o sha256 é o que faz "a mesma versão" significar "os mesmos bytes".

Por onde seguir#