El mes pasado dejo de ser beta una iniciativa muy interesante llamada Conventional Commits.
Se trata de una especificación para dar significado a los mensajes de los commits haciéndolos legibles para máquinas y humanos.
Esta especificación proporciona un conjunto fácil de reglas para crear un historial de commits explícito. Esta convención se ajusta a SemVer, al describir las características, correcciones y cambios que rompen la compatibilidad en los mensajes de los commits.
En la empresa en la que trabajo ya veníamos utilizando SemVer y desde la semana pasada, hemos decidido probar a utilizar Conventional Commits en nuestro día a día.
Resumen de la convención
[tipo]([ámbito opcional]): [descripción] [cuerpo opcional] [nota de pie opcional]
Ejemplo sólo con los campos obligatorios:
feat: cambiar títulos y estilos en la página de inicio
Ejemplo completo:
feat(home): añadir pie alternativo a la home Implementar una versión alternativa del pie de página Agregar iconos alternativos en la versión móvil del pie de página Soluciona la incidencia #3
Tipo (obligatorio)
El tipo de commit es obligatorio indicarlo.
Tipos de commits principales
- fix: corrige un error (se correlaciona con PATCH en el versionado semántico).
- feat: introduce nuevas funcionalidades (se correlaciona con MINOR en el versionado semántico).
Otros tipos de commits
Está permitido cualquier tipo, pero se recomiendan los que usa Angular convention. Ejemplos recomendados:
- build: cambios que afectan el sistema de compilación o dependencias externas (gulp, broccoli, npm...)
- ci: cambios en nuestros archivos y scripts de configuración de CI.
- docs: cambios en la documentación.
- improvement: mejorar una implementación actual sin añadir nuevas características ni corregir errores.
- perf: cambio en el código que mejora el rendimiento.
- refactor: mejora en el código que no corrige un error ni añade funcionalidad.
- style: cambios cosméticos en el código que no afectan a la funcionalidad (formateo, espacios en blanco, tabuladores, etc.).
- test: añadidos nuevos tests o corregidos estistentes.
Ámbito (opcional)
Se puede agregar un ámbito al tipo de commit para proveer información contextual adicional. Es opcional y se escribe entre paréntesis.
Ejemplo:
feat(parser): añadir capacidad de parsear arrays
Descripción (obligatoria)
Es obligatoria una descripción corta de los cambios realizados en el código.
Cuerpo (opcional)
Un cuerpo del commit más extenso PUEDE agregarse después de la descripción, dando información contextual adicional acerca de los cambios en el código. El cuerpo DEBE iniciar con una línea en blanco después de la descripción.
Nota de pie (opcional)
Una nota de pie PUEDE agregarse tras una línea en blanco después del cuerpo o después de la descripción en caso de que no se haya dado un cuerpo. La nota de pie DEBE contener referencias adicionales a los números de problemas registrados sobre el cambio del código (como el número de problema que corrige, ejemplo Corrige incidencia #154).
Commit que rompe la compatibilidad hacia atrás
Siempre que se produzca un commit (sea del tipo que sea) que rompa la compatibilidad hacia atrás, se debe indicar con un texto BREAKING CHANGE: en el pie.
En lugar del BREAKING CHANGE: o de manera adicional, se puede usar un signo ! tras el tipo/ámbito.
Ejemplo:
refactor!: eliminado soporte para Node 6 BREAKING CHANGE: refactorizar para usar características de JavaScript no disponibles en Node 6
Estos commits se correlacionan con MAJOR en el versionado semántico.
Bola extra: CHANGELOG.md automático
Existe un paquete NPM llamado standard-version que nos permite crear el documento CHANGELOG.md de manera automatizada si nos ajustamos a Conventional Commits.