Los releases generalmente se crean cada cierto tiempo según la metodología de desarrollo que se esté usando en el equipo de trabajo, en un equipo scrum por ejemplo cada dos semanas se puede hacer un release después de finalizar un spring. Una solución que he encontrado para generar automáticamente gran parte de estas tareas es utilizar el paquete release-it.

Que es un release

Repositorio

Un release es una instantania/copia de un proyecto capturada en un momento en el que existe un mínimo producto viable, el cual nos sirve de backup y de referencia ya que contiene la documentación de lo que se hizo hasta ese lanzamiento.

Generalmente un release debe contener:

  • Unas anotaciones (CHANGELOG) donde se describe que características se introdujeron o los bugs que se corrigieron, agregando los links necesarios para que estos sean trazables, como ejemplo links al commit/rama o a la tarea en jira.
  • Una etiqueta (TAG) que lo distinga, esta debe estar acorde a las especificaciones dados por semantic version, ejemplo v1.0.0
  • Unos archivos binarios comprimidos que representan el estado actual del proyecto y/o los entregables asociados al código.

La idea original de tener un release es presentar un proyecto funcional o mínimo viable, esto significa que contiene una cantidad de características que combinadas proveen una o varias funcionalidades que se han acordado previamente con el cliente o entre el mismo equipo de trabajo.

Los releases generalmente se crean cada cierto tiempo según la metodología de desarrollo que se esté usando en el equipo de trabajo, en un equipo scrum por ejemplo cada dos semanas se puede hacer un release después de finalizar un spring, o cada cierto mes según la complejidad del proyecto y los lineamientos del director del proyecto.

Tareas para hacer en un lanzamiento

Existen varias tareas que se deben hacer antes de lanzar un release que pueden hacerlo una tarea muy tediosa:

  • Comprobar la calidad del código, para esto se puede usar un linter.
  • Comprobar el estado del código, para esto debemos correr test unitarios y de integración con herramientas como jest, mocha entre otras.
  • Mantener una cobertura adecuada de test en nuestro código, para este podemos usar istanbul o jest.
  • Generar el tag de versionamiento y actualizar el package.json.
  • Documentar cada uno de los cambios, actualizaciones o correcciones que se hicieron para consolidarlos en un CHANGELOG.
  • Generar una copia comprimida del proyecto en su estado actual.

Automatizando un release

Una solución que he encontrado para generar automáticamente gran parte de estas tareas es utilizar el paquete release-it, el cual nos permite con un archivo de configuración y un comando, crear nuestro tag, generar automáticamente el CHANGELOG a partir del historial de git, hacer el push a nuestro repositorio y generar los archivos binarios respectivos.

Para agregar esta utilidad a nuestro proyecto debemos instalar dos paquetes, auto-changelog el cual se encarga de crear el changelog a partir del historial de los commit (git log) y release-it el cual se encarga de automatizar todas las tareas para hacer un lanzamiento.

 > npm install auto-changelog --save-dev
 > npm install release-it --save-dev

El primer paso es crear un archivo vacío en la raíz llamado CHANGELOG.md y un archivo changelog-template.hbs que va a contener la estructura del historial. Vamos a agregar en los scripts del packaje.json el comando para generar.

 > touch CHANGELOG.md
 > touch changelog-template.hbs

/** package.json **/
 {
   ...
  "scripts": {
    "changelog": "auto-changelog --template changelog-template.hbs --unreleased && git add CHANGELOG.md"
  },
  ...
}

Segundo debemos crear el archivo de configuración .release-it.json en el cual vamos a agregar los script necesarios antes, durante y después de generar el release, aquí también se agregan todas las configuraciones según el administrador de repositorios que estemos manejando (github, gitlab, bitbucket). Y agregamos el script a package.json

/** package.json **/
 {
   ...
  "scripts": {
    "release": "release-it",
  },
  ...
}

/** .release-it.json **/
 {
  "pkgFiles": ["package.json", "package-lock.json"],
  "scripts": {
    "beforeStart": "npm run test:cov && npm run test:e2e",
    "beforeStage": "npm run changelog",
    "afterRelease": "echo Successfully released ${name} v${version} to ${repo.repository}."
  },
  "git": {
    "pushRepo": "origin"
  },
  "github": {
    "release": true,
    "tokenRef":  "GITHUB_RELEASE_IT_TOKEN",
    "draft": true
  },
  "npm": {
    "publish": false
  }
}
}

Si trabajamos con github o gitlab debemos generar un token desde sus plataformas, con el cual vamos a tener permisos para acceder al repositorio, en bitbucket no tenemos que generar nada.

Debemos agregar ese token a nuestro archivo de configuración release-it, es recomendable utilizar variables de entorno para no exponer esta información.

Hasta este punto ya tenemos configurada nuestra herramienta, y no debemos repetir más este procedimiento.

Creando un release

  • Para generar un release debemos sacar una rama de desarrollo que cumpla con el estándar se semantic version ejemplo: release/1.0.0.

  • Nuestra rama debe ser reconocida por el servidor por eso debe ser trackeada con git push –u release-branch, este paso es obligatorio.

  • Corremos npm run release, este comado corre nuestro paquete release-it, el cual nos muestra varias opciones las cuales debemos darle que si, en este punto antes de hacer push recomiendo verificar el changelog.

  • Se genera una rama del release y entonces debemos hacer un pull request a develop y a master, verificando que se actualicen correctamente las versiones y los archivos package.

  • En github y gitlab podemos ver que se genera un draft, un tag los cuales podemos liberar y modificar desde la herramienta, una vez hagamos los merge a master y a develop. Bitbucket algunas características como el draft, por lo demos funciona igual.