Conventional commits (o Commits convencionales) es una evolución ligada al Versionado Semántico o SemVer de los mensajes commit básicos (según las 7 reglas de un buen mensaje commit). Siguen el patrón:

<tipo>(ámbito opcional): <descripción>
«LÍNEA EN BLANCO»
Cuerpo opcional
«LÍNEA EN BLANCO»
Nota(s) al pie opcional(es)

No escribas más de 50 caracteres en la primera línea, y no más de 72 por línea para el resto. Y respeta las líneas en blanco cuando incluyas dos o los tres apartados del patrón.

<tipo>(ámbito opcional): <descripción>

Donde <tipo> puede ser:

  • fix cuando el cambio corrige un error. Se relaciona con PARCHE (PATCH) en SemVer.
  • feat cuando introduces una nueva funcionalidad. Se relaciona con MENOR (MINOR) en SemVer.
  • Otros tipos están permitidos. Por ejemplo, la guía para contribuir a Angular propone los siguientes:
    • build cuando el cambio afecta a la compilación del proyecto.
    • ci cuando el cambio afecta a ficheros de configuración y scripts relacionados con la integración continua.
    • docs cuando sólo se modifica documentación.
    • style por cuestiones de legibilidad o de formato del código sin afectar a una funcionalidad.
    • refactor para los cambios que no corrigen errores ni añaden funcionalidades, pero mejoran el código.
    • perf para los cambios que introducen mejoras en el rendimiento.
    • test para añadir o corregir código de los tests.

Si introduces un cambio que rompe la API pública del código entonces debes indicarlo en el mensaje. Por ejemplo con el carácter ! después del tipo/ámbito, o añadiendo un BREAKING CHANGE en la Nota al pie. Un BREAKING CHANGE puede ser parte de commits de cualquier tipo. Se relaciona con MAYOR (MAJOR) en SemVer.

El ámbito (scope) es opcional, permite guardar información del contexto del cambio. Por ejemplo para indicar el nombre de la característica a la que afecta el commit. Verbigracia, common, core, elements, forms, http, server, etc…

La descripción (description) debe ser breve, usando imperativos como «añade» en lugar de «añadido» o «añadidos», con la primera letra en minúscula y sin escribir punto al final. Evita las generalidades o descripciones fuera de contexto. Y si te cuesta trabajo resumir, quizás estás aplicando demasiados cambios a la vez.

Cuerpo opcional

  • Omite el Cuerpo (Body) si el resumen es suficiente para explicar el contenido y el contexto.
  • Mantén el tono imperativo. Puedes usar varias frases y crear listas con guiones o asteriscos. Las frases sí terminan con punto.
  • Debes explicar el qué y el por qué, en lugar de el cómo; para que futuros colaboradores entiendan las razones de haber escogido una solución frente a otras.

Nota(s) al pie opcional(es)

  • El Pie (Footer) también es opcional.
  • Es útil para enumerar las peticiones cerradas o afectadas por el cambio (separadas por coma si son más de una).
  • También es un buen lugar para indicar los cambios que rompen la compatibilidad de la API usando el formato:
BREAKING CHANGE: <descripción>

Ejemplo de un mensaje commit

feat(common)!: Actualiza con 50 caracteres o menos

Texto explicativo opcional más detallado, usando 72 caracteres o menos
por línea. En general, la primera línea se puede interpretar como el
asunto en un correo electrónico y el resto como el cuerpo.

Se explica el problema que resuelve este commit, QUÉ hace y POR QUÉ lo
hace. Para el CÓMO basta con mirar el código. Si hay efectos secundarios
u otras consecuencias poco intuitivas con este cambio, también hay que
explicarlo.

La línea en blanco que separa el resumen del cuerpo es crítica (a menos
que se omita el cuerpo por completo); varias herramientas como `log`,
`shortlog` o `rebase` pueden confundirse si no se deja esa línea en
blanco.

Otros párrafos pueden venir después de líneas en blanco:

 - Se pueden escribir listas de viñetas como esta.

 - Normalmente se usa un guión o un asterisco para la viñeta, precedido
   por un espacio y con líneas en blanco en el medio, pero aquí las
   convenciones pueden variar.

En el pie, se pueden poner referencias a las peticiones relacionadas que
se han cerrado o tienen interés. Por ejemplo:

BREAKING CHANGE: usa características no disponibles en la versión anterior.
Resuelve #123, #456

Para revertir un commit

Si el commit revierte uno anterior entonces puedes usar el siguiente formato:

revert(ámbito opcional): <descripción>
«LÍNEA EN BLANCO»
Se revierte la aplicación del commit {hash}.

donde {hash} es el SHA del commit que se revierte.

Última revisión: 10/10/2022

0 comentarios

Dejar un comentario

¿Quieres unirte a la conversación?
Siéntete libre de contribuir!

Deja una respuesta

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *