Reglas de nomenclatura de número de versión
Dirección reimpresa: https://semver.org/lang/zh-CN/
Versión semántica 2.0.0
Resumen
Formato de versión: número de versión principal. Número de versión menor. Número de revisión. Las reglas para incrementar el número de versión son las siguientes:
- Número de versión principal: cuando realiza cambios de API incompatibles,
- Número de versión menor: cuando crea una nueva función para compatibilidad con versiones anteriores,
- Número de revisión: cuando solucionó problemas de compatibilidad con versiones anteriores.
El número de versión avanzada y los metadatos de compilación de la versión se pueden agregar después del "número de versión principal. Número de versión menor. Número de revisión" como una extensión.
Introduccion
En el campo de la administración de software, hay un valle de la muerte llamado "infierno de dependencia". Cuanto más grande es el sistema, más paquetes se unen y más probabilidades hay de que te encuentres desesperado algún día.
Publicar una nueva versión del paquete en un sistema altamente dependiente pronto puede convertirse en una pesadilla. Si la dependencia es demasiado alta, puede correr el riesgo de que se bloquee el control de versiones (debe revisar cada paquete de dependencia para completar una actualización determinada). Si las dependencias son demasiado flexibles, será imposible evitar el caos de las versiones (suponiendo que varias versiones compatibles con el futuro hayan excedido un número razonable). Cuando el progreso de su proyecto se bloquea y el caos de la versión no es simple y confiable, significa que está en una gran dependencia.
Como una de las soluciones a este problema, propongo usar un conjunto simple de reglas y condiciones para restringir la configuración y el crecimiento de los números de versión. Estas reglas se basan en (pero no se limitan a) convenciones que han sido ampliamente utilizadas por varios software de código abierto y cerrado. Para que esta teoría funcione, primero debe tener una API pública bien definida. Esto se puede lograr a través de definiciones de documentos o requisitos de aplicación del código. En cualquier caso, la claridad de esta API es muy importante. Una vez que defina la API pública, puede explicar sus cambios a todos modificando el número de versión correspondiente. Considere el uso de dicho formato de número de versión: XYZ (número de versión principal. Número de versión menor. Número de revisión) cuando el problema se soluciona pero no afecta a la API, incremente el número de revisión; cuando la API sigue siendo compatible con versiones nuevas y modificadas, incremente el número de versión menor; Al realizar cambios incompatibles, incremente el número de versión principal.
Yo llamo a este sistema "control de versión semántico". Bajo este conjunto de convenciones, el número de versión y su método de actualización contienen información sobre el código subyacente y el contenido modificado entre versiones adyacentes.
Especificación de control de versión semántica (SemVer)
Las siguientes palabras clave DEBEN, NO DEBEN, REQUERIRSE, DEBERÁN, NO DEBERÁN, DEBERÁN, DEBERÍAN, RECOMENDARSE, MAYO, OPCIONAL, se interpretan de acuerdo con RFC 2119. (Anotación: para mantener la oración fluida, las palabras clave que se encuentran en los siguientes documentos se traducirán de acuerdo con la semántica de la oración completa, y aquí no se realizará ninguna traducción individual).
-
El software que usa versiones semánticas debe (DEBE) definir una API pública. La API se puede definir en el código o aparecer en un archivo riguroso. Cualquiera sea la forma, debe esforzarse por la precisión y la integridad.
-
El número de versión estándar debe (DEBE) estar en formato XYZ, donde X, Y y Z son enteros no negativos, y NO DEBE rellenar ceros delante del número. X es el número de versión principal, Y es el número de versión secundario y Z es el número de revisión. Cada elemento debe (DEBE) aumentar de valor. Por ejemplo: 1.9.1-> 1.10.0-> 1.11.0.
-
Después de que se publique el software marcado con el número de versión, NO DEBE cambiar el contenido del software de esa versión. Cualquier cambio debe (DEBE) lanzarse en una nueva versión.
-
El software con un número de versión principal de cero (0.yz) se encuentra en la etapa inicial de desarrollo, y todo se puede cambiar en cualquier momento. Dicha API pública no debe considerarse una versión estable.
-
El número de versión 1.0.0 se utiliza para definir la formación de la API pública. Después de esta versión, todas las actualizaciones de número de versión se basan en la API pública y sus modificaciones.
-
El número de revisión Z (xyZ
|x> 0) debe (DEBE) incrementarse solo cuando se realiza una corrección compatible hacia abajo. Las correcciones aquí se refieren a los cambios internos realizados para obtener resultados incorrectos. -
El número de versión menor Y (xYz
|x> 0) debe (DEBE) incrementarse cuando aparecen nuevas características compatibles con versiones anteriores. También debe incrementarse (DEBE) cuando la funcionalidad de cualquier API pública está marcada como obsoleta. Mayo (MAYO) se incrementa cuando se agrega una gran cantidad de nuevas funciones o mejoras al programa interno, lo que puede incluir cambios en el nivel de revisión. Cada vez que se incrementa el número de versión menor, el número de revisión debe (DEBE) restablecerse a cero. -
El número de versión principal X (Xyz
|X> 0) debe (DEBE) incrementarse cuando se agregan cambios incompatibles a la API pública. Entre ellos puede (MAYO) incluir número de versión menor y cambios de nivel de revisión. Cada vez que se incrementa el número de versión principal, el número de versión menor y el número de revisión deben (DEBE) restablecerse a cero. -
El número de versión principal (MAYO) se puede marcar después de la revisión, primero agregue un número de conexión y luego una serie de identificadores separados por puntos para modificar. El identificador debe (DEBE) estar compuesto por caracteres alfanuméricos ASCII y el número de conexión [0-9A-Za-z-], y NO DEBE dejarse en blanco. Los identificadores digitales NO DEBEN rellenar con ceros al frente. La versión anterior tiene menor prioridad que la versión estándar asociada. Ser etiquetado con el número de versión avanzada indica que esta versión no es estable y puede no cumplir con los requisitos de compatibilidad esperados. Ejemplos: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92.
-
Los metadatos de la compilación de la versión pueden marcarse (MAYO) después de la revisión o el número de versión anterior, seguidos de un signo más seguido de una serie de identificadores separados por puntos. El identificador debe (DEBE) estar compuesto por caracteres alfanuméricos ASCII y el número de conexión [0-9A-Za-z-], y NO DEBE dejarse en blanco. Al juzgar el nivel de prioridad de la versión, se pueden ignorar los metadatos de compilación de la versión. Por lo tanto, cuando las dos versiones difieren solo en los metadatos de compilación de la versión, pertenecen al mismo nivel de prioridad. Ejemplos: 1.0.0-alpha + 001, 1.0.0 + 20130313144700, 1.0.0-beta + exp.sha.5114f85.
-
El nivel de prioridad de las versiones se refiere a cómo se comparan las diferentes versiones al ordenar. Al juzgar el nivel de prioridad, debe (DEBE) dividir la versión en orden de número de versión principal, número de versión secundaria, número de revisión y número de versión anterior para la comparación (los metadatos de compilación de la versión no están en esta lista de comparación). Compare cada identificador en orden de izquierda a derecha. El primer valor de diferencia se utiliza para determinar el nivel de prioridad: el número de versión principal, el número de versión menor y el número de revisión se comparan por valor, por ejemplo: 1.0.0 <2.0.0 <2.1.0 <2.1.1. Cuando el número de versión principal, el número de versión menor y el número de revisión son iguales, está determinado por el número de versión anterior con un nivel de prioridad más bajo. Por ejemplo: 1.0.0-alpha <1.0.0. Hay dos números de versión principales con el mismo número de versión principal, número de versión secundaria y número de revisión, y sus niveles de prioridad deben (DEBE) compararse a través de cada identificador separado por períodos de izquierda a derecha hasta que se encuentre un valor de diferencia Decisión: los identificadores con solo números se comparan con el valor numérico, y cuando hay letras o números de conexión, se comparan entre sí en orden ASCII. Los identificadores digitales tienen una prioridad menor que los identificadores no numéricos. Si los identificadores al principio son los mismos, el número de versión anterior con más campos tiene mayor prioridad. Ejemplo: 1.0.0-alpha <1.0.0-alpha.1 <1.0.0-alpha.beta <1.0.0-beta <1.0.0-beta.2 <1.0.0-beta.11 <1.0.0- rc.1 <1.0.0.
¿Por qué usar versiones semánticas?
Esta no es una idea nueva o revolucionaria. De hecho, es posible que ya estés haciendo algo similar. El problema es que la "aproximación" no es suficiente. Si no hay una especificación formal a seguir, el número de versión no tiene un significado sustantivo para la gestión de dependencias. Nombrar las ideas anteriores y darles una definición clara le facilita transmitir sus intenciones a los usuarios de software. Una vez que estas intenciones se vuelven claras, se pueden lograr especificaciones dependientes flexibles (pero no demasiado flexibles).
Un ejemplo simple puede mostrar cómo el control semántico de versiones hace del infierno de la dependencia una cosa del pasado. Supongamos que hay una biblioteca llamada "Firetruck", necesita otro paquete llamado "Ladder" y ya tiene versiones semánticas. Cuando se creó el camión de bomberos, el número de versión de la escalera era 3.1.0. Debido a que Firetruck utiliza algunas de las nuevas características en la versión 3.1.0, puede especificar con seguridad que el número de versión que depende de la escalera es mayor que 3.1.0 pero menor que 4.0.0. De esta manera, cuando se lanzan las versiones de escalera 3.1.1 y 3.2.0, puede incluirlas directamente en su sistema de administración de paquetes porque son compatibles con el software dependiente original.
Como desarrollador responsable, debe asegurarse de que el funcionamiento de cada actualización del paquete sea coherente con el número de versión. El mundo real es complicado, y no hay mucho que podamos hacer, excepto aumentar nuestra vigilancia. Todo lo que puede hacer es dejar que el control de versión semántico le brinde una forma sólida de lanzar y actualizar paquetes sin la necesidad de lanzar nuevos paquetes dependientes, ahorrándole tiempo y problemas.
Si está de acuerdo con esto y desea comenzar a usar versiones semánticas de inmediato, solo debe declarar que su biblioteca lo está usando y seguir estas reglas. Mantenga este enlace de página en su archivo README para que otros conozcan estas reglas y se beneficien de ellas.
Preguntas más frecuentes
En la etapa de desarrollo inicial de 0.yz, ¿cómo realizo el control de versiones?
La forma más fácil es utilizar 0.1.0 como versión de desarrollo inicial e incrementar el número de versión secundaria con cada versión posterior.
¿Cómo juzgar cuándo lanzar la versión 1.0.0?
Cuando su software se utiliza en un entorno formal, debería haber alcanzado la versión 1.0.0. Si ya tiene una API estable en la que confían los usuarios, será la versión 1.0.0. Si le preocupa la compatibilidad con versiones anteriores, debe considerar la versión 1.0.0.
¿Esto no obstaculizará el rápido desarrollo y la iteración?
Cuando el número de versión principal es cero, es para un desarrollo rápido. Si está cambiando la API todos los días, aún debería estar en la etapa donde el número de versión principal es cero (0.yz), o en la rama de desarrollo independiente de la próxima versión principal.
Para las API públicas, si incluso los cambios más pequeños pero incompatibles requieren un nuevo número de versión principal, ¿no alcanzaría pronto la versión 42.0.0?
Esta es una cuestión de responsabilidad de desarrollo y visión de futuro. Los cambios incompatibles no deben agregarse fácilmente al software con muchos códigos dependientes. El costo de la actualización puede ser enorme. Incrementar el número de versión principal para emitir revisiones incompatibles significa que debe pensar cuidadosamente sobre el impacto de estos cambios y evaluar las relaciones de costo y beneficio involucradas.
¡Escribir documentos para toda la API pública es demasiado problema!
Es su responsabilidad como desarrollador profesional escribir archivos apropiados para el software para que otros lo usen. Una parte muy importante para mantener un proyecto eficiente es controlar la complejidad del software. Si nadie sabe cómo usar su software o no sabe qué funciones son confiables, será difícil controlar la complejidad. A la larga, el uso de versiones semánticas y la buena adherencia a las API públicas permitirán que todos y todo funcione sin problemas.
¿Qué sucede si accidentalmente libero una revisión incompatible como un número de versión menor?
Una vez que descubra que ha roto la especificación del control de versiones semántico, debe solucionar el problema y emitir un nuevo número de versión menor para corregir el problema y restaurar la compatibilidad con versiones anteriores. Incluso en este caso, no puede modificar la versión lanzada. Si es posible, registre el número de versión problemática en el archivo y dígale al usuario dónde está el problema, para que pueda darse cuenta de que esta es la versión problemática.
¿Qué sucede si actualizo mis dependencias pero no cambio la API pública?
Como no afecta a la API pública, esto puede considerarse compatible. Si cierto software y su paquete tienen una dependencia común, tendrá su propia especificación de dependencia, y el autor también informará sobre posibles conflictos. Para determinar si la revisión es un nivel de revisión o un nivel de subversión, se basa en sus dependencias actualizadas para solucionar problemas o agregar nuevas características. Para este último, a menudo espero estar acompañado de más código, que obviamente será un incremento del nivel de número de versión menor.
¿Qué sucede si cambio la API pública pero, sin querer, no sigo el cambio del número de versión? (Lo que significa que en el lanzamiento del nivel de revisión, se agregaron por error cambios importantes e incompatibles al código)
Haz tu mejor juicio. Si tiene una gran base de usuarios que se verá muy afectada al cambiar el comportamiento de acuerdo con la intención de la API pública, es mejor hacer una versión de versión principal, incluso si estrictamente hablando, esta solución es solo una versión de nivel de revisión. Recuerde, el control semántico de la versión es transmitir significado a través del cambio del número de versión. Si estos cambios son importantes para sus usuarios, explíqueles a través del número de versión.
¿Qué debo hacer con las funciones que quedarán en desuso?
Abandonar las funciones existentes es común en el desarrollo de software y, por lo general, es necesario para avanzar. Cuando desaprueba parte de la API pública, debe hacer dos cosas: (1) actualizar su archivo para que los usuarios sepan sobre el cambio, (2) desaprobar la función en un momento adecuado a través del nuevo número de versión menor Publicar Antes de que la nueva versión principal elimine por completo la función de desaprobación, al menos una versión secundaria contiene esta información de desaprobación para que los usuarios puedan transferir sin problemas a la nueva versión de la API.
¿La versión semántica limita la longitud de la cadena de la versión?
No, por favor haga los juicios apropiados usted mismo. Por ejemplo, la versión de 255 caracteres es exagerada. Además, ciertos sistemas pueden tener sus propias restricciones sobre la longitud de la cadena.
Acerca de
La especificación para el control de la versión semántica fue establecida por Tom Preston-Werner , fundador de Gravatars y cofundador de GitHub .
Si tiene alguna sugerencia, publique sus preguntas en GitHub .
Permiso
