NIP 14 – Gestión de Versiones para Paquetes de Symbol

Introducción

Este documento describe el ciclo de lanzamiento estándar para todos los paquetes alojados en la organización nemtech.

Especificación

Versión

Todos los proyectos deben adherirse a Semantic Versioning 2.0.0.

Dado un número de versión MAJOR.MINOR.PATCH, incremente la versión: MAYOR cuando realice cambios de API incompatibles, la versión MENOR cuando agregue funcionalidad de manera compatible con versiones anteriores y la versión PATCH cuando realice correcciones de errores compatibles con versiones anteriores.

Las versiones entre proyectos deben permanecer independientes.

Registro de Cambios

Las nuevas versiones deben incluir un CHANGELOG basado en Keep a Changelog.

Si un proyecto tiene dependencias con otros paquetes de símbolos, el CHANGELOG debe adjuntar la siguiente tabla por cada nueva versión que describa las dependencias:

Hito: nombre del hito del servidor de catapulta (número de versión)

LibreríaVersiónPaquete
Nombre de Libreria v0.17.3 Enlace al paquete

Herramienta

La mayoría de nuestros proyectos usan TravisCI como la herramienta de automatización de CI, pero puede usar Jenkins o cualquier otra herramienta que se adapte al proceso si se siente más cómodo con él.

Prueba de Juicio

Cada vez que hay una nueva confirmación, los scripts de compilación deberían:

  • Construcción de paquetes
  • Ejecución de ruebas unitarias

GitHub debería evitar fusionar los RP que no cumplan los requisitos mencionados anteriormente.

Desarrollo Alpha

Cada vez que hay un nuevo impulso para dominar, los scripts de compilación deben generar e implementar una nueva versión comprobable como 0.17.1-ALPHA-20200220T120318.

Tenga en cuenta que hay un sufijo de marca de tiempo ya que los administradores de paquetes pueden no permitir la implementación de la misma versión. Si el administrador de paquetes permite la implementación de SNAPSHOT, no es necesario utilizar una marca de tiempo en este caso.

La marca de tiempo es generada automáticamente por la herramienta de automatización de CI. No debería haber ningún proceso manual como escribir la versión 0.17.1-ALPHA-1 o 0.17.1-ALPHA-2.

Un cliente puede usar una dependencia alfa como “symbol-sdk”: “0.17.1-ALPHA-20200220T120318”.

Versión Completa

Cada vez que queremos lanzar, creamos un PR desde el maestro hasta la rama de lanzamiento. El PR incluirá la actualización CHANGELOG explicando las nuevas características.

Una vez que se aprueba PR, la herramienta de automatización de CI lo recogerá, compilará y luego realizará un lanzamiento.

El script de lanzamiento debe:

  • git etiqueta la versión que se lanzará (por ejemplo: v0.17.4)
  • Publicar la versión actual en el administrador de paquetes (por ejemplo, npm, docker hub – 0.17.4)
  • Actualizar la versión del paquete (por ejemplo: 0.17.5 usando el parche de la versión npm)
  • Agregar y confirmar cambios
  • Empujar confirmaciones en la rama maestra (por ejemplo: package.json tendrá el nuevo 0.17.5)
  • Empujar la etiqueta (v0.17.4)

Motivación

Proceso de lanzamiento estandarizado

La forma en que se realiza el proceso de lanzamiento se confirma y documenta en el archivo y las secuencias de comandos de travis. No se hace en una máquina de desarrollo. Cualquiera puede entenderlo y realizar un lanzamiento.

Circuito de retroalimentación más estricto

Los usuarios deben esperar una versión adecuada antes de comenzar a usar una nueva función en nuestros paquetes. Aunque el proceso es bastante dinámico, podrían pasar algunos días antes de obtener una versión que agregue muchas mejoras juntas.

La propuesta es agregar la versión y el token correctos en los scripts de la herramienta de automatización de CI para que cada vez que se fusione un RP con un maestro, una tubería empuje una nueva alfa / instantánea al administrador de paquetes. Si un usuario está esperando una solución, esa solución se incluirá en el administrador de paquetes automáticamente después de fusionar el nuevo maestro.

Lanzamientos más rápidos

Utilizando la instantánea, el equipo de Symbol puede realizar comprobaciones y comentarios adicionales antes de realizar un lanzamiento, probando con humo el artefacto de la instantánea en otros proyectos como la CLI, la billetera o el explorador. Incluso los ejemplos en los documentos se pueden actualizar antes de lanzar el paquete.

Implementación

El Symbol SDK para Typecript sigue el ciclo de lanzamiento definido en este documento usando TravisCI.

Nota: La implementación depende del marco y el lenguaje de programación, la implementación de TS es solo un ejemplo.

  • travis.yml: https://github.com/nemtech/symbol-sdk-typescript-javascript/blob/master/.travis.yml
  • Lanza script: https://github.com/nemtech/symbol-sdk-typescript-javascript/blob/master/travis/release.sh
  • Alfa lanza script: https://github.com/nemtech/symbol-sdk-typescript-javascript/blob/master/travis/uploadArchives.sh

Ajustes de Travis

Travis tendrá los tokens necesarios y las claves de cifrado para realizar un lanzamiento utilizando variables env. Los más comunes son:

  • NPM_TOKEN: el token utilizado para insertar artefactos npm en un repositorio npm https://docs.npmjs.com/creating-and-viewing-authentication-tokens
  • GITHUB_TOKEN: el token utilizado para impulsar los aumentos de versión, etiquetas y documentación (páginas de GitHub) en GitHub. El usuario debe poder publicar desde la rama de lanzamiento a master una vez que se actualice la versión. https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line
  • RELEASE_BRANCH: el nombre de la rama de lanzamiento. Ejemplo: lanzamiento.
  • (Opcional): signatureKeyId, SignaturePassword, SignatureSecretKeyRingFile y la clave privada cifrada de Travis. Los valores necesarios para los paquetes de signos. https://medium.com/@nmauti/sign-and-publish-on-maven-central-a-project-with-the-new-maven-publish-gradle-plugin-22a72a4bfd4b

Necesitaríamos otros tokens para definir las implementaciones de Docker, Sonar o PIP.

Los tokens generados deben ser de usuarios con permisos suficientes (por ejemplo, un usuario que puede pasar a la rama de páginas de GitHub o npm).

Proyectos siguiendo el NIP

  •  symbol-sdk-typescript-javascript OK
  •  symbol-sdk-java OK
  •  symbol-cli OK
  •  symbol-openapi OK
  •  symbol-openapi-generator OK
  •  catbuffer-generators Pendiente
  •  symbol-docs Pendiente
  •  catapult-rest Pendiente
  •  catapult-server Pendiente

Compatibilidad de Antecedentes

No hay problemas de incompatibilidad con precedentes. Los artefactos cargados son los mismos, recién implementados desde Travis en lugar de una máquina desarrolladora.

Contribuciones

Un agradecimiento especial a @dgarcia360 y @rg911 por contribuir activamente a este NIP.

Fuente: Github de NEM