Conventional Commits. Cómo estandarizar el proceso de creación

A medida que una empresa o departamento incrementa su tamaño, crecen también los retos y dificultades técnicas a las que es necesario enfrentarse. Estos retos suceden, principalmente, por el incremento de personas y por el aumento de la complejidad en los proyectos que se manejan. Mis compañeros del área CMS de hiberus Digital, Adrián Marín y Alejandro Arnau lo saben muy bien y lo explicaron perfectamente en una charla llamada ‘Transformación Ágil a Escala: Liderando +150 Expertos en Drupal en Proyectos Globales’ que impartieron durante la pasada DrupalCamp Spain que se celebró en Sevilla del 20 al 23 de septiembre.

En este artículo quiero contaros cómo hemos resuelto uno de esos retos y cómo esta solución se ha aplicado a otras áreas de hiberus Digital para estandarizar el proceso de creación de commits en un repositorio Git.

Cuando hace unos años nuestra área era mucho más pequeña de lo que es hoy en día y los equipos que trabajaban en un proyecto eran más reducidos, era fácil mantener la uniformidad en la creación de commits y conseguir que todos los desarrolladores del área siguieran unas reglas comunes a la hora de escribir los mensajes de estos commits.

A medida que el equipo fue creciendo y se fueron incorporando más desarrolladores nos encontramos con una situación en la que, debido al número de proyectos simultáneos y a la complejidad creciente de los mismos, mantener estas reglas comunes se hacía muy complicado, obligando a los líderes técnicos del área a un esfuerzo extra para controlar el tono, el estilo y la relevancia de los mensajes. Esta situación nos obligó a buscar una solución para solucionarla. Después de revisar y evaluar varias alternativas decidimos apostar por el uso de Conventional Commits.

¿Qué es Conventional Commits?

Tal como indica su página oficial, Conventional Commits es una especificación para dar significado a los mensajes de commits haciéndolos comprensibles tanto para las máquinas como para las personas. Proporciona un conjunto sencillo de reglas para crear un historial de commits explícito, lo que hace más fácil poder escribir herramientas automatizadas.

Dicha especificación o convención define una serie de reglas para escribir los mensajes de commit que consiguen mejorar la legibilidad del histórico del repositorio y posibilitan tener herramientas que automaticen procesos basados en el historial de commits.

Está basada e inspirada en las Commit Message Guidelines del proyecto Angular.

Al poder describir en los mensajes de los commits las funcionalidades, arreglos y cambios de ruptura hechos, esta convención encaja a la perfección con Semantic Versioning o Semver.

Se trata de la convención más extendida para establecer un versionado a librerías, paquetes o dependencias, estableciendo tres bloques separados:

• MAJOR: número de versión que se incrementa cuando se rompe la compatibilidad de versiones anteriores.
• MINOR: número de versión que se incrementa cuando se añade funcionalidad y esta es compatible en la versión MAJOR actual.
• PATCH: número de versión que se incrementa cuando se arreglan errores en la versión MAJOR.MINOR actual.

Estructura

Según esta especificación, un mensaje de commit debe estructurarse de la siguiente forma:

• tipo: tipo de commit, refiriéndose a su contenido.
• ámbito: opcional, sirve para dar información contextual. Ej.: nombre del módulo o paquete
• descripción: el asunto del commit
• cuerpo: opcional, debería aportar más información que la descripción
• nota al pie: opcional, se usa para indicar meta información sobre el commit

Tipo

Indica el tipo de commit, refiriéndose a su contenido.

La especificación ofrece una guía para los tipos, aunque puede modificarse y/o adaptarse a las necesidades de cada equipo o empresa.

Existen diferentes listas de tipos recomendados, la que más nos gusta es la siguiente:

• build: cambios relacionados con la construcción o compilación, por ejemplo, cuando se añaden herramientas externas.
• chore: un cambio en el código que un usuario externo no verá, por ejemplo, un cambio en el archivo .gitignore
• feat: una característica nueva
• fix: una corrección de errores
• docs: cambios relacionados con la documentación
• refactor: un cambio que no corrige un error ni añade una característica, por ejemplo, cuando se renombra una variable o función.
• perf: código que mejora el rendimiento
• style: un código relacionado con el estilo
• test: añadir un nuevo test o hacer cambios en un test existente

Ámbito

El campo ámbito es opcional y sirve para dar información contextual como por ejemplo indicar el nombre del módulo o paquete al que afecta el commit.

Puede ser complicado determinar si se tiene que usar o no, pero en caso de usarse tiene que ir entre paréntesis.

Un listado de posibles ámbitos es:

• theme
• init
• runner
• watcher
• config
• web-server
• proxy

Descripción

Se trata del asunto del commit, debe cumplir las siguientes reglas:

• Debemos usar el imperativo en inglés o el infinitivo en español
• La primera letra siempre irá en minúscula
• No tenemos que escribir un punto al final
• El tamaño no debería exceder los 50 caracteres

Cuerpo

Es opcional y solo se debería añadir si aporta más información que la descripción.

Las reglas para crear la descripción son:

• Empieza después de una línea en blanco.
• Se usa el imperativo/infinitivo, al igual que en la descripción
• Debe tener una anchura máxima de 72 caracteres, aunque se pueden tener múltiples líneas.
• Solamente debe contener explicaciones de “¿Qué?” (what) y “¿Por Qué?” (why), nunca de ¿Cómo? (How). Esta explicación del “¿Cómo?” se debería hacer en la documentación, si es necesario.

Nota al pie

Es opcional y se usa para indicar meta información sobre el commit.

Las reglas para la escritura de las notas al pie son:

• Empieza después de una línea en blanco.
• Debería usarse en las siguientes situaciones
  • Para indicar cambios que rompan la compatibilidad de la versión actual
  • Para mostrar uno o varios pull-request relacionados
  • Para mostrar los revisores del commit
• Si se incluyen varios de estos temas, cada uno de ellos en una línea independiente

Algunos ejemplos del uso de esta especificación en nuestros proyectos

Próximos pasos

Con esta especificación implementada en varias de nuestras áreas de manera satisfactoria, en hiberus nos planteamos cuáles serían los siguientes pasos para mejorar la calidad de nuestros proyectos usando git como base de nuestros repositorios de código.

Adicionalmente al uso de la especificación de Conventional Commits, el uso de Merge Request con Gitlab nos ayuda a realizar revisiones por pares en aquellos proyectos en los que es necesario.

De la misma forma, tenemos implementado un sistema de generación de documentación en formato MKDocs, usando un contenedor dentro del proyecto, de manera que dicha documentación se almacena dentro del propio repositorio y está disponible para cualquier desarrollador en el momento en que se clona el proyecto.

En próximos post comentaremos cómo automatizar la generación de changelogs, tags y releases dentro de los proyectos mediante diferentes herramientas como Semantic release y Commitizen. Ambas herramientas funcionan de manera similar y nos permitirán ir un paso más allá en la automatización de los procesos internos de desarrollo.

En el área digital de hiberus estamos encantados de acompañarte en la estrategia de tu negocio. Si tienes dudas, consúltanos y conoce nuestros servicios. ¡Te ayudaremos a relanzar y aumentar los resultados de tu negocio!