Versões das dependências

Versionamento semântico

Pacotes no Yarn seguem o padrão do Versionamento Semântico, também conhecido como “semver”. Quando você instala um novo pacote a partir do registro, ele será adicionado em seu arquivo package.json com um intervalo de versão semver.

Essas versões são compostas por três diferentes números de versão: maior.menor.correção. Exemplos de versões assim são: 3.14.1, 0.42.0, 2.7.18. Cada parte da versão é incrementada em certos momentos:

  • Incremente maior quando você fizer uma mudança que quebra ou torna incompatível a API de um pacote em relação à versão anterior.
  • Incremente menor quando você adicionar novas funcionalidades enquanto permanece compatível com versões anteriores.
  • Incremente correção quando você realizar correções de erros enquanto permanece compatível com versões anteriores.

Nota: Por vezes, há também “rótulos” ou “extensões” no formato semver que marcam coisas como versões pré-lançamento ou beta (por exemplo, 2.0.0-beta.3).

Quando desenvolvedores falam sobre duas versões de semver sendo “compatíveis” uma com a outra, eles estão se referindo a mudanças compatíveis com versões anteriores (menor e correção).

Intervalos de versão

Quando você quiser especificar uma dependência, você vai normalmente especificar seu nome e o intervalo de versão no seu arquivo package.json, como nesses exemplos:

{
  "dependencies": {
    "pacote-1": ">=2.0.0 <3.1.4",
    "pacote-2": "^0.4.2",
    "pacote-3": "~2.7.1"
  }
}

Você notará que, além do número de versão, temos também alguns outros caracteres. Esses caracteres, >=, <, ^, e ~, são operadores e são usados para especificar os intervalos de versão.

O propósito de um intervalo de versão é especificar quais versões de uma dependência irão funcionar no seu código.

Comparadores

Cada intervalo de versão é composto de comparadores. Estes comparadores são simplesmente um operador seguido por uma versão. Aqui estão alguns dos operadores básicos:

Comparador Descrição
<2.0.0 Qualquer versão que seja menor que 2.0.0
<=3.1.4 Qualquer versão que seja menor ou igual a 3.1.4
>0.4.2 Qualquer versão que seja maior que 0.4.2
>=2.7.1 Qualquer versão que seja maior ou igual a 2.7.1
=4.6.6 Qualquer versão que seja igual a 4.6.6

Nota: se nenhum operador for especificado, então o operador do intervalo de versão é considerado como =. Por isso, o operador = é puramente opcional.

Interseções

Comparadores podem ser unidos por um espaço em branco para criar um conjunto de comparadores. Isso cria uma interseção entre os comparadores inclusos. Por exemplo, o comparador >=2.0.0 <3.1.4 significa “Maior ou igual a 2.0.0 e menor que 3.1.4".

Uniões

Um intervalo de versão completo pode incluir uma união de vários conjuntos de comparadores unidos por ||. Se qualquer um dos lados da união for satisfeito, então todo o intervalo de versão é satisfeito. Por exemplo, o intervalo de versão <2.0.0 || >3.1.4 significa “Menor que 2.0.0 ou maior que 3.1.4".

Tags de pré-lançamento

Versões também podem ter tags de pré-lançamento (ex. 3.1.4-beta.2). Se um comparador inclui uma versão com uma tag de pré-lançamento, ele só irá corresponder às versões que tenham a mesma versão maior.menor.correção.

Por exemplo, o intervalo >=3.1.4-beta.2 corresponderia a 3.1.4-beta.2 ou 3.1.4-beta.12, mas não corresponderia a 3.1.5-beta.1, mesmo que seja tecnicamente “maior ou igual” (>=) à versão 3.1.4-beta.2.

Pré-lançamentos costumam conter alterações que acidentalmente quebram a compatibilidade, e normalmente você não quer usar pré-lançamentos fora da versão que você especificou. Esse comportamento é útil para casos assim.

Intervalos de versão avançados

Intervalos de hífen

Intervalos de hífen (ex. 2.0.0 - 3.1.4) especificam um conjunto inclusivo. Se parte da versão for deixada de fora (ex. 0.4 ou 2), ela será preenchida com zeros.

Intervalo de versão Intervalo de versão expandido
2.0.0 - 3.1.4 >=2.0.0 <=3.1.4
0.4 - 2 >=0.4.0 <=2.0.0
Intervalos-X

Qualquer um desses, X, x ou *, pode ser usado para deixar parte ou toda uma versão não especificada.

Intervalo de versão Intervalo de versão expandido
* >=0.0.0 (qualquer versão)
2.x >=2.0.0 <3.0.0 (corresponde com a versão maior)
3.1.x >=3.1.0 <3.2.0 (corresponde com as versões maior e menor)

Se parte de uma versão for omitida, presume-se ser um “intervalo x”.

Intervalo de versão Intervalo de versão expandido
`` (string vazia) * ou >=0.0.0
2 2.x.x ou >=2.0.0 <3.0.0
3.1 3.1.x ou >=3.1.0 <3.2.0
Intervalo de til (~)

Usar ~ com uma versão menor especificada permite alterações de correção. Usar ~ apenas com a versão maior especificada permitirá mudanças de versão menor.

Intervalo de versão Intervalo de versão expandido
~3.1.4 >=3.1.4 <3.2.0
~3.1 3.1.x ou >=3.1.0 <3.2.0
~3 3.x ou >=3.0.0 <4.0.0

Nota: Especificar pré-lançamentos em intervalos de til corresponderá somente a pré-lançamentos na mesma versão completa. Por exemplo, o intervalo de versão ~3.1.4-beta.2 corresponderia com 3.1.4-beta.4 mas não com 3.1.5-beta.2 porque a versão maior.menor.correção é diferente.

Intervalos de acento circunflexo

Permite alterações que não modificam o primeiro dígito diferente de zero na versão - por exemplo, o 3 em 3.1.4 ou o 4 em 0.4.2.

Intervalo de versão Intervalo de versão expandido
^3.1.4 >=3.1.4 <4.0.0
^0.4.2 >=0.4.2 <0.5.0
^0.0.2 >=0.0.2 <0.0.3

Nota: Por padrão, quando você executa yarn add [nome-do-pacote], ele usará um intervalo de acento circunflexo.

Se parte da versão for deixada de fora, as partes restantes serão preenchidas com zeros. No entanto, eles ainda permitirão que esse valor seja alterado.

Intervalo de versão Intervalo de versão expandido
^0.0.x >=0.0.0 <0.1.0
^0.0 >=0.0.0 <0.1.0
^0.x >=0.0.0 <1.0.0
^0 >=0.0.0 <1.0.0

Mais recursos