¿Cuál es la sintaxis de la versión Bower (y npm)?

Bower me permite especificar requisitos de versión para paquetes usando la siguiente sintaxis:

"dependencies": {
  "<name>": "<version>",
},

Pero no he podido encontrar cuál es la sintaxis para usar <version>. Sé que puedo especificar versiones para ser:

• mayor que una cierta versión con ">1.0.0"
• mayor o igual que una versión: ">=1.0.0"
• o en algún rango: "1.0.0 - 2.0.0".

También sé que hay una versión de la sintaxis común que contiene la tilde: "~1.0.0". Pero no estoy seguro de lo que significa y si es lo mismo que "=1.0.0".

También me interesa saber si puedo especificar varias versiones no consecutivas, como exactamente 1.0.3más versiones mayores que 1.5.0, etc.

En pocas palabras, la sintaxis para los números de versión de Bower (y NPM) se llama SemVer, que es la abreviatura de 'Versión Semántica'. Puede encontrar documentación para la sintaxis detallada de SemVer como se usa en Bower y NPM en la API para el analizador semver en Node / npm . Puede obtener más información sobre la especificación subyacente (que no menciona ~u otros detalles de sintaxis) en semver.org .

Hay una calculadora visual semver muy útil con la que puedes jugar, lo que hace que todo esto sea mucho más fácil de asimilar y probar.

¡SemVer no es solo una sintaxis! Tiene algunas cosas bastante interesantes que decir sobre las formas correctas de publicar API, lo que ayudará a comprender qué significa la sintaxis. Crucialmente:

Una vez que identifica su API pública, le comunica los cambios con incrementos específicos a su número de versión. Considere un formato de versión de XYZ (Major.Minor.Patch) . Las correcciones de errores que no afectan la API incrementan la versión del parche, las adiciones / cambios de API compatibles con versiones anteriores incrementan la versión menor, y los cambios de API incompatibles con versiones anteriores aumentan la versión principal.

Entonces, su pregunta específica se ~relaciona con ese esquema Major.Minor.Patch. (Al igual que el operador de intercalación relacionado ^). Puede ~reducir el rango de versiones que está dispuesto a aceptar para:

• cambios posteriores a nivel de parche a la misma versión menor ( "correcciones de errores que no afectan a la API" ), o:
• cambios posteriores de menor nivel a la misma versión principal ( "adiciones / cambios de API compatibles con versiones anteriores" )

Por ejemplo: para indicar que tomará cualquier cambio posterior a nivel de parche en el árbol 1.2.x, comenzando con 1.2.0, pero menor que 1.3.0, puede usar:

"angular": "~1.2"
  or:
"angular": "~1.2.0"

Esto también le ofrece los mismos resultados que con la .xsintaxis:

"angular": "1.2.x"

Pero, puede usar la tilde / ~sintaxis para ser aún más específico: si solo está dispuesto a aceptar cambios en el nivel de parche que comiencen con 1.2.4 , pero aún menos que 1.3.0, usaría:

"angular": "~1.2.4"

Moviéndose a la izquierda, hacia la versión principal , si usa ...

"angular": "~1"

... es lo mismo que ...

"angular": "1.x"
  or:
"angular": "^1.0.0"

... y coincide con cualquier cambio menor o de nivel de parche por encima de 1.0.0, y menos de 2.0:

Tenga en cuenta que la última variación anterior: se llama 'rango de intercalación' . El cursor se parece muchísimo a un >, por lo que sería excusado por pensar que significa "cualquier versión mayor que 1.0.0". (Ciertamente me he resbalado en eso.) ¡No!

Los rangos de atención se utilizan básicamente para decir que solo le importa el dígito más significativo de la izquierda, generalmente la versión principal, y que permitirá cualquier cambio menor o de nivel de parche que no afecte a ese dígito de la izquierda. Sin embargo, a diferencia de un rango de tilde que especifica una versión principal, los rangos de intercalación le permiten especificar un punto de inicio menor / parche preciso. Entonces, mientras ^1.0.0 === ~1, un rango de intercalación como le ^1.2.3permite decir que tomará cualquier cambio >=1.2.3 && <2.0.0. No podrías hacer eso con un rango de tilde.

Todo eso parece confuso al principio, cuando lo miras de cerca. Pero aleja la imagen por un segundo y piénsalo de esta manera: el cursor simplemente te permite decir que estás más preocupado por cualquier dígito significativo que quede más a la izquierda. La tilde le permite decir que está más preocupado por el dígito más adecuado. El resto es detalle.

Es el poder expresivo de la tilde y el caret lo que explica por qué las personas los usan mucho más que la .xsintaxis más simple : simplemente te permiten hacer más. Es por eso que verá que la tilde se usa a menudo, incluso donde .xserviría. Como ejemplo, vea npm: su propio archivo package.json incluye muchas dependencias en el ~2.4.0formato, en lugar del 2.4.xformato que podría usar. Al apegarse a ~, la sintaxis es consistente en toda una lista de más de 70 dependencias versionadas, independientemente de qué número de parche inicial sea aceptable.

De todos modos, aún hay más en SemVer, pero no intentaré detallarlo todo aquí. Compruébelo en el archivo léame del paquete semver del nodo . Y asegúrese de usar la calculadora de versiones semánticas mientras practica e intenta entender cómo funciona SemVer.

RE: Números de versión no consecutivos: la pregunta final de OP parece ser sobre la especificación de números / rangos de versión no consecutivos (si lo he editado de manera justa). Sí, se puede hacer eso, utilizando el doble tubería común "o" operador: ||. Al igual que:

"angular": "1.2 <= 1.2.9 || >2.0.0"

Basado en semver , puedes usar

• Rango de guiones XYZ - ABC 1.2.3-2.3.4 indica > = 1.2.3 <= 2.3.4

• Rangos X 1.2.x 1.X 1.2.*

• Tilde Ranges ~1.2.3 ~1.2 Indica que permite cambios a nivel de parche o cambios menores en la versión.

• Caret Rangos ^ 1.2.3 ^ 0.2.5 ^ 0.0.4

  Permite cambios que no modifican el dígito más a la izquierda que no es cero en la tupla [mayor, menor, parche]

  • ^1.2.x (significa> = 1.2.0 <2.0.0)
  • ^0.0.x (significa> = 0.0.0 <0.1.0)
  • ^0.0 (significa> = 0.0.0 <0.1.0)

Bower usa la sintaxis semver , pero aquí hay algunos ejemplos rápidos:

Puedes instalar una versión específica:

$ bower install jquery#1.11.1

Puede usar ~ para especificar 'cualquier versión que comience con esto':

$ bower install jquery#~1.11

Puede especificar múltiples requisitos de versión juntos:

$ bower install "jquery#<2.0 >1.10"

También puede usar la latestpalabra clave para instalar la versión más reciente disponible:

  "dependencies": {
    "fontawesome": "latest"
  }

Si no hay un número de parche, ~es equivalente a agregar .xa la versión sin tilde. Si hay un número de parche, ~permite todos los números de parche> = el especificado.

~1     := 1.x
~1.2   := 1.2.x
~1.2.3 := (>=1.2.3 <1.3.0)

No tengo suficientes puntos para comentar sobre la respuesta aceptada, pero parte de la información tilde está reñida con la documentación vinculada semver: "angular": "~1.2"se no coincidir con 1.3, 1.4, 1.4.9. Además "angular": "~1"y no"angular": "~1.0" son equivalentes. Esto se puede verificar con la calculadora npm semver .