Conventional Commits - Especificación para tus mensajes de commit

¿Qué son los mensajes de commit?

Los mensajes de commit son una forma de documentar los cambios que se realizan en un repositorio de código. Estos mensajes son muy útiles para entender qué cambios se realizaron en un proyecto, y por qué se hicieron.

Cuando se trabaja en un equipo de desarrollo, es muy importante que todos los miembros del equipo puedan entender qué cambios se realizaron en el código, y por qué se realizaron.

Conventional Commits

Como dice su página oficial : 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. Esta convención encaja con SemVer , ya que podemos explicar en los mensajes de commits, si es una feature, bugfix, incluso si hay "Breaking Changes*.

Si no conocías el término de Semantic Versioning, en este vídeo corto te lo cuento:

La estructura de un mensaje de commit siguiendo la especificación sería la siguiente:

<tipo>[scope opcional]: <descripción del commit>

[cuerpo del mensaje, opcional]

[footer(s), opcionales]

Tipos de commits

Los tipos de commits son los siguientes:

• feat: Una nueva característica o funcionalidad. Tendría correlación con una versión MINOR siguiendo SemVer.
• fix: Un error corregido. Tendría correlación con una versión PATCH siguiendo SemVer.
• BREAKING CHANGE: Un cambio que contenga esta palabra en el footer del mensaje o un signo ! despues del tipo o scope, rompe la compatibilidad con versiones anteriores. Tendría correlación con una versión MAJOR siguiendo SemVer.

Se permiten también los siguientes tipos:

• build: Cambios que afectan el sistema de compilación o dependencias externas (ej. cambios en el package.json).
• ci: Cambios en nuestros archivos y scripts de configuración de integración continua.
• docs: Cambios en la documentación.
• chore: Otros cambios que no afectan el código fuente.
• perf: Un cambio de código que mejora el rendimiento.
• refactor: Un cambio de código que no corrige un error ni agrega una característica.
• style: Cambios que no afectan el significado del código (espacios en blanco, formato, puntos y comas faltantes, etc).
• test: Agregar pruebas faltantes o corregir pruebas existentes.

Scope

El scope es opcional, y sirve para especificar el alcance del commit. Por ejemplo, si estamos trabajando en un proyecto monorepo, podemos especificar el paquete que estamos modificando.

Ejemplos

Veamos algunos ejemplos de mensajes de commit siguiento la especificación:

Commit que añade una nueva característica, sin un scope en concreto.

feat: add support for TypeScript

Commit que arregla un bug, dentro del paquete ui de nuestro proyecto.

fix(ui): bugfix on Button component

Commit que rompe la compatibilidad con versiones anteriores, aunque no añade características nuevas ni corrige bugs.

chore!: drop support for Node 6

BREAKING CHANGE: use JavaScript features not available in Node 6.

Commit que agrega pruebas faltantes

test(ui): add missing tests for Button component

Commit que agrega una tarea para el sistema de integración/despliegue continuo.

ci: add GitHub Actions workflow

Commit con un mensaje descriptivo largo y varios footers o pie de página.

fix(api): prevent duplicate users from being created

This commit fixes a bug where the API would allow duplicate users to be created
with the same email address. This commit also adds a new `unique` constraint to
the `users` table to prevent this from happening in the future.

Paired with: X
Fixes #123

¿Por qué usar Conventional Commits?

• Permite la generación automática del fichero CHANGELOG.
• Determina automáticamente los cambios de versión siguiendo SemVer (basado en los tipos de commits utilizados).
• Comunican la naturaleza de los cambios a los demás integrantes del equipo o cualquier persona interesada.
• Activa los procesos de build y despliegue o publicación.
• Hacer más fácil a otras personas contribuir al proyecto al permitirles explorar el historial de commits de una forma más estructurada.

Herramientas para usar Conventional Commits

Plugin de VSCode

La primera que utilizo es la extensión o plugin de VSCode, Conventional Commit . Me ayuda a elegir el tipo de commit, el scope, escribir el mensaje,... todo a base de ventanas de dialogo.

Gitemoji

Para darle más colorido a nuestros commits, podemos usar la convención Gitemoji . Es una convención en la que los emojis representan el tipo de commit. Por ejemplo, el emoji 🐛 representa un bugfix, ✨ un nuevo feature, etc... Así de un vistazo rápido puedes ver que tipo de cambio se ha realizado.

Commitlint

Commitlint es una herramienta que nos permite configurar reglas para validar los mensajes de commit. Igual que usamos un linter para comprobar si seguimos ciertas reglas de estilo en nuestro código, lo podemos usar para los mensajes de commit.

Para ello necesitas instalar la librería @commitlint/cli y @commitlint/config-conventional en tu proyecto.

npm install --save-dev @commitlint/cli @commitlint/config-conventional

Una vez instaladas, debes crear un fichero de configuración llamado commitlint.config.js en la raíz de tu proyecto con el siguiente contenido:

module.exports = {
  extends: ["@commitlint/config-conventional"],
};

Husky

Ya vimos para que servía Husky en un post anterior. Ahora vamos a añadirle una nueva regla al hook pre-commit para que verifique y valide si el mensaje de commit cumple las reglas de la convención Conventional Commits.

Si ya tienes configurado Husky lo único que has de hacer es ejecutar el siguiente comando en la raíz de tu proyecto para que añada el comando al hook commit-msg:

npx husky add .husky/commit-msg  'npx --no -- commitlint --edit ${1}'

Y listo, cada vez que hagas un commit, verificará que sigue las reglas.

CHANGELOG

Por último, también es interesante poder generar automáticamente el fichero CHANGELOG a partir de los mensajes de commit. Para ello hay diversas herramientas, una de ellas es Conventional Changelog