Convenciones commit GIT
Escribir buenos mensajes de commit es importante para que el histórico de tu proyecto sea legible, claro y entendible por cualquier persona que participe en el proyecto.
Ventajas
Las ventajas de aplicar convenciones a los commits de GIT son diversas.
- Generación automática de CHANGELOGs.
- Determinación automática de los cambios de versión (basado en los tipos de commits).
- Comunicar la naturaleza de los cambios a los demás integrantes del equipo, el público o cualquier otro interesado.
- Ejecutar procesos de ejecución y publicación.
- Hacer más fácil a otras personas contribuir al proyecto, permitiendo explorar una historia de los commits más estructurada.
- Uniformidad e imagen presentable del proyecto.
Reglas
Regla a tomar en cuenta:
- Usar el verbo imperativo (fix, refactor, feat, ...)
- No usar punto final ni puntos suspensivos en tus mensajes.
- Añadir todo el contexto que sea necesario en el cuerpo del mensaje de commit.
- Usar SIEMPRE un prefijo para tus commits para hacerlos más semánticos. Ejemplo: [feat]
Template de un commit
Un mensaje de commit está compuesto por tres partes:
- Titular: <type>(<scope>): <subject>
- Cuerpo: <body>
- Pie: <footer>
Titular
El título del mensaje de commit deberá ser menor a 70 caracteres, dejando una nueva línea entre el título y el cuerpo del commit. Al momento de redactar el titular del mensaje deberá seguirse el siguiente formato:
<type>(<scope>): <subject>
Tipos (type)
Los <type> se refieren al tipo de suceso que es representado con el commit, estos sucesos son de diversas índoles y suelen ser representados como un verbo en imperativo. Para el proyecto actual se han definido los siguientes "type".
- feat: Una nueva característica o funcionalidad.
- fix: Representa la corrección de una falla (bug) dentro del proyecto.
- perf: Cambios que mejoran el rendimiento del sitio.
- build: Cambios en el sistema de build, tareas de despliegue o instalación.
- ci: Cambios en la integración continua.
- docs: Representa cambios en la documentación del proyecto.
- style: Representa cambios en el estilo (interfaz) del proyecto.
- refactor: Representa modificaciones y cambios para optimizar y mejorar el diseño y/o arquitectura.
- test: Representa cambios o creación en pruebas del proyecto (unitarias, integración, funcionales, aceptación, …)
- chore: Representa cambios o creación en archivos que no afectan funcionalidades programáticas del sistema.
- revert: Si el commit revierte un commit anterior. Debería indicarse el hash del commit que se revierte.
Ámbitos (scope)
Los (<scope>) representan el módulo sobre el que se está confirmando los cambios. El (<scope>) puede ser vació siempre y cuando sean cambios globales (para todo el proyecto) o cuando es difícil determinar el módulo o si los cambios aplican para más de un módulo.
Los ámbitos disponibles de forma predeterminada son los siguientes:
- init: Cuando se inicializa un repositorio
Nota: Los ámbitos de un proyecto pueden ser los módulos disponibles dentro del sistema que se está construyendo.
Cuerpo
El cuerpo del mensaje del commit deberá dar información de utilidad y concisa que ayude a determinar en un vistazo de que se trata el cambio que se está llevando a cabo, de modo que no de lugares a dudas. Normalmente, se suele escribir y detallar de forma genérica el cómo se resolvió sin entrar en detalles tan técnicos.
Sin embargo, en caso de usar un sistema de seguimiento de información que genere identificadores de "issues" (Jira, Redmine, bugtrack, Github, Gitlab, Mantis, etc.) es preferible apuntar al identificador del "issue" para evitar la repetición de información y documentación. Siendo que la documentación detallada será aplicada en el sistema de seguimiento. Si el commit corresponde a un issue con un solo identificador, entonces es posible representar el commit como:
Closes #9658
Para diversos issues que se están cerrando simplemente basta con separarlos usando ",":
Closes #896, #489, #145
Pie
Si existe un cambio que es muy peligroso y que puede dañar diversas características es requerido que se coloque en el pie del commit, el cual consiste en una línea en blanco después del cuerpo del mensaje:
BREAKING CHANGE: lexer del traductor depende de una nueva base de datos modelada en #896, esta base de datos no es igual a las anteriores, puesto que si existen dependencias directas (no deberían) es requerido que se actualicen. O en caso de utilizar una interfaz de acceso, solo se requiere que se utilice el nuevo schema descrito en #896-doc. En caso de necesitar automatizar la migración, mirar la herramienta loremipsum-tool para agilizar la detección y migración.
Línea de comando
git commit -m "sujeto" -m "descripción..."
El primer argumento -m es para el título (corta descripción), y el siguiente es para la descripción extendida (cuerpo del mensaje).
Ejemplos de commits
Mensaje de commit con descripción
[feat]: allow provided config object to extend other configs
Cambio que rompe la compatibilidad en el cuerpo
[BREAKING CHANGE]: 'extends' key in config file is now used for extending other config files
Mensaje de commit sin cuerpo
[docs]: correct spelling of CHANGELOG
Mensaje de commit con ámbito
[feat] (lang): added polish language
Mensaje de commit para una corrección usando un número de problema (opcional)
[fix]: minor typos in code
see the issue for details on the typos fixed
fixes issue #12
FAQ
¿Se deben escribir los tipos de los commits en mayúscula o minúscula?
En minúscula.
¿Qué debo hacer si un commit encaja en más de un tipo de commit?
Regrese y haga múltiples commits de ser posible. Parte de los beneficios de los commits convencionales es la habilidad para hacer commits más organizados y así mismo PRs.
¿Qué debo hacer si por accidente uso un tipo de commit equivocado?
Cuando utiliza un tipo que es de la especificación, pero no es el correcto, e.g. fix en lugar de feat
Antes de combinar o liberar el error, recomendamos usar git rebase -i para editar el historial de los commits. Después de que se ha liberado, la limpieza será distinta de acuerdo con las herramientas y procesos que usted use.
Cuando se usa un tipo que no está en la especificación, e.g. feet instead of feat
En el peor de los escenarios, no es el fin del mundo si aparece un commit que no cumple con las especificaciones de los commits convencionales. Simplemente, el commit será ignorado por las herramientas que se basen en esta especificación.