¿Qué es Conventional Commits?

Conventional Commits es una especificación que establece varios estándares para mejorar la consistencia y la claridad de los mensajes de commit de Git, generando así un historial de commits mucho más limpio, funcional y apto para automatizaciones.

Ventajas de usar Conventional Commits

Aplicar la especificación de Conventional Commits tiene muchas ventajas, entre ellas:

• Estandariza los mensajes de commit, de forma que todos siguen una estructura similar y facilita la búsqueda de información.
• Mejora la utilidad de los mensajes, incluyendo información más relevante (el tipo de modificación, el alcance, o incluso el identificador de la incidencia en Jira).
• Facilita la generación de changelogs.
• Hace posible automatizar la generación de documentación, ya que el formato es el mismo para todos los commits.
• Puede ayudar a determinar la versión del proyecto a partir de los «tipos» de commit.
• Ayuda a la gente no implicada en el desarrollo a entender los cambios realizados.

Todas estas ventajas hacen que Conventional Commits sea una mejora muy significativa en los flujos de trabajo.

La especificación

Conventional Commits define la estructura de los mensajes de commit de la siguiente manera:

tipo(alcance opcional): descripción

cuerpo opcional

pie opcional

Tipo de cambio

Es obligatorio indicar un tipo de cambio. Los principales son:

• feat: cuando se añade una nueva funcionalidad al proyecto.
• fix: cuando se corrige un error.

Sin embargo, existen más tipos que podemos usar:

• build: cuando el cambio afecta al sistema de build o a las dependencias.
• ci: para los cambios que impactan en la integración continua.
• docs: cuando se actualiza la documentación.
• perf: indica que los cambios mejoran el rendimiento.
• refactor: para refactorizaciones de código que no corrigen errores ni añaden funcionalidad.
• style: cambios al formato del código (como espacios en blanco).
• test: para cambios que afectan al testing (por ejemplo, añadir pruebas unitarias).
• revert: revierte un cambio previo.

El alcance

Es opcional indicar un alcance: la especificación sugiere que debería ser un sustantivo que describa una sección del código y debe estar entre paréntesis.

La descripción

Es obligatorio y debe ser una descripción concisa (una línea corta) de los cambios realizados.

El cuerpo

Opcionalmente se puede añadir el cuerpo, que es una descripción más larga (sin límite de longitud) que se puede incluir en el commit. Debe haber una línea en blanco entre la descripción y el cuerpo.

El pie de commit

Por último, podemos añadir uno o más pies de commit para incluir referencias.

Un pie de commit debe consistir de una palabra «clave» (o varias, separadas por guiones, ya que la especificación no permite espacios en la clave), a continuación dos puntos (:) y un espacio o, en lugar de esto, un espacio y una almohadilla, y finalmente el texto «valor» que corresponde al pie.

La única «clave» que admite espacios es «BREAKING CHANGE», que indica más información acerca de un cambio importante en una API. También es válido escribirlo como «BREAKING-CHANGE» si así se desea.

Otras consideraciones de formato

A continuación del tipo y el alcance (si lo hay) se incluye:

• Opcionalmente, un signo de exclamación para indicar un «breaking change» (un cambio significativo en una API).
• Obligatoriamente, dos puntos (:) seguidos de un espacio.

Además, el «BREAKING CHANGE» en el pie se puede omitir si se utiliza el signo de exclamación a continuación del tipo y alcance.

Un ejemplo vale más que mil palabras 😊

Esto sería un ejemplo válido del uso de Conventional Commits:

feat(calculadora)!: añade un nuevo parámetro para la división

Se añade un nuevo parámetro para indicar si se debe obtener el resto de la división.

Revisado-por: EM
Jira: CALCULADORA-1234
BREAKING CHANGE: requiere indicar el nuevo parámetro.

Como puedes ver, la especificación tiene una capacidad significativa para mejorar los flujos de trabajo y la automatización, y su uso se recomienda enormemente.

Puedes revisar más en detalle la especificación en el sitio oficial de Conventional Commits.