Las ventajas de aplicar convenciones en los mensajes de confirmación son diversas, sin embargo las mas importantes son las siguientes:
- Dar legibilidad a los eventos que ocurren dentro del código fuente que es generado dentro del repositorio
- Agilizar la búsqueda y rastreo de funcionalidades que intervengan en un suceso(bugs, requerimientos, etc).
- Automatizar generación de reportes y estadísticas para medir el código y su calidad.
- Uniformidad e imagen presentable del proyecto
Las practicas descritas en este post están inspiradas de la guiá de git para el proyecto Karma: https://karma-runner.github.io/2.0/dev/git-commit-msg.html
Template de un commit
Un mensaje de confirmación esta compuesto por tres partes:
- Titular:
<type>(<scope>): <subject> - Cuerpo:
<body> - Pie:
<footer>
El titulo del mensaje de confirmación deberá ser menor a 70 caracteres , dejando una nueva línea entre el titulo y el cuerpo de la confirmación. Al momento de redactar el titular del mensaje deberá seguirse el siguiente formato:
<type>(<scope>): <subject>
Tipos(type) disponibles
Los <type> se refieren al tipo de suceso que es representado con la confirmación, 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” en ingles que serán requeridos implementar según convenga:
- feat: Se utiliza cuando se esta confirmando una nueva característica estable, es decir que es algo que no se ha creado antes.
- fix: Representa la corrección de una falla(bug) dentro del proyecto.
- 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.
Los (<scope>) representan el módulo sobre el que se esta 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 de un proyecto pueden ser los módulos disponibles dentro del sistema que se esta construyendo.
Los ámbitos disponibles de forma predeterminada son los siguientes:
- init: Cuando se inicializa un repositorio
- Global
- Doc
El cuerpo del mensaje de confirmación deberá dar información de utilidad y concisa que ayude a determinar en un vistazo de que se trata el cambio que se esta llevando acabo de modo que no de lugares a dudas. Normalmente se suele escribir y detallar de forma genérica el como se resolvió sin entrar en detalles tan técnicos.
Sin embargo en caso de usar un sistema de planeación de información que genere identificadores de “issues”(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 planificación y rastreo. Si la confirmación corresponde a un issue con un solo identificador entonces es posible representar el commit como:
Para diversos issues que se están cerrando simplemente basta con separarlos usando “,”:
Si existe un cambio que es muy peligroso y que puede dañar diversas características (no debería si existe ortogonalidad y correcto versionado semántico) es requerido que se coloque en el pie de la confirmación, el cual consiste en una línea en blanco después del cuerpo del mensaje:
‘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.
Ejemplos de commit
Confirmación simple:
Refactor(Parser): Reestructurar generador de arboles
Se refactoriza el sistema que genera arboles, debido a que existía dos servicios que hacían prácticamente lo mismo. Se procedió a implementar MVC REST para variar el formato de representación sin tener que cambiar los nodos al recurso y generar código repetido.
Confirmación simple basada en issues:
Closes #2365 #7896
Confirmación con pie:
En caso de necesitar automatizar la migración mirar la herramienta loremipsum-tool para agilizar la detección y migración
Se refactoriza el sistema que genera arboles, debido a que existía dos servicios que hacían prácticamente lo mismo. Se procedió a implementar MVC REST para variar el formato de representación sin tener que cambiar los nodos al recurso y generar código repetido.
‘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.
Confirmación con pie e issues:
Refactor(Parser): Reestructurar generador de arbolesBREAKING 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.
Template de un commit
<body>
<footer>
y...
En protzimas entradas veremos como tomar los commits de un proyecto para automatizar la tarea de hacer reportes e inspeccionar sistemas, usando perl y bash.
Comentarios
Publicar un comentario