Entre las herramientas habituales de los programadores está el control de versiones del código fuente, siendo Git el sistema más usado. Cuando se contribuye al repositorio de un proyecto (commit) se requiere un mensaje que explique las modificaciones introducidas en el código.
Se recomienda la presente guía de buenas prácticas para:
- ayudar a entender los cambios sin tener que revisar el código;
- simplificar y normalizar la navegación a través del historial de Git; y
- filtrar los cambios para facilitar la generación del archivo CHANGELOG.
Plantilla para un mensaje de commit
Op asunto [ámbito]
«LÍNEA EN BLANCO»
Cuerpo
«LÍNEA EN BLANCO»
Pie
Por legibilidad, la primera línea de resumen no debería tener más de 50 caracteres, y el resto no más de 72. Visual Studio Code y otros entornos de desarrollo tienen en cuenta estos límites para facilitar la escritura de estos mensajes.
No olvidar que las líneas en blanco deben respetarse si se incluyen dos o los tres apartados de la plantilla.
Línea resumen: Op asunto [ámbito]
Donde:
Op
debe comenzar con letra mayúscula:- Añade (Add) – una nueva funcionalidad para los usuarios.
- Modifica (Change) – alguna característica de una funcionalidad dada.
- Elimina (Remove) – definitivamente una funcionalidad obsoleta.
- Corrige (Fix) – un error que afecta al usuario.
- Asegura (Security) – o mitiga una vulnerabilidad en el código.
- Mejora (Improve) – el rendimiento o el uso de una funcionalidad existente.
- Actualiza (Update) – sin añadir ni modificar funcionalidades, por ejemplo al refactorizar código, añadir documentación o incluir scripts de compilación y configuraciones.
- Retoca (Tweak) – alguna particularidad del aspecto o una funcionalidad determinada.
- Inicia (Initial) – para empezar el proyecto; por ejemplo Inicia el repositorio (Initial commit).
- Integra (Merge) – la petición de fusión #123 de algúnusuario/algunarama.
- Libera (Release) – la versión X.Y.Z del proyecto.
asunto
(subject) debe completar la frase imperativa del resumen y terminar sin punto.ámbito
(scope) es opcional, omitiendo los corchetes si no se indica. Según el proyecto se pueden definir ámbitos comoconfig
,logging
,common
,framework
,middleware
,tests
,database
,lib
,reporting
,doc
,browser
,events
,preprocessor
,webserver
,proxy
,license
, etc…
Hay que evitar las generalidades o los resúmenes fuera de contexto, teniendo en cuenta que si cuesta trabajo resumir quizás se están haciendo demasiados cambios a la vez.
Cuerpo
- El Cuerpo (Body) se omitirá si el resumen es suficiente para explicar el contenido y el contexto.
- Se pueden usar varias frases y crear listas con guiones o asteriscos. Las frases sí terminan con punto.
- Debe explicar el qué y el por qué, en lugar de el cómo; para que futuros colaboradores puedan saber las razones de haber escogido una solución frente a otras.
Pie
- El Pie (Footer) es opcional.
- Es útil para indicar las peticiones relacionadas que se han cerrado o se han visto afectadas (separadas por coma si son más de una).
Revertir un commit
Si el commit revierte uno anterior se usará el siguiente formato:
Revierte "Resumen del commit revertido"
«LÍNEA EN BLANCO»
Se revierte la aplicación del commit {hash}.
donde {hash}
es el SHA del commit que se revierte.
Ejemplo de un mensaje de commit
Actualiza el resumen 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:
Resuelve #123, #456
Ver también #789
Generando el archivo CHANGELOG
Una de las utilidades más inmediatas de un registro de mensajes cuidado y trabajado es la generación del archivo CHANGELOG.
Por ejemplo, podríamos crear un script para generar el archivo CHANGELOG según los valores Op del asunto de los mensajes agrupándolos en tres apartados: Funcionalidades o Características (Añade, Modifica, Mejora, Elimina), Corrección de errores (Corrige) y Seguridad (Asegura). Luego sólo habría que repasarlo para eliminar o depurar los mensajes recogidos.
Usando Git se puede obtener la lista de todos los commits. Por ejemplo, con sólo el texto del asunto y el identificador completo:
git log {etiqueta} HEAD --pretty=format:%s
o en una versión web:
git log v2.1.0...v2.1.1 --pretty=format:'‹li›‹a href="https://gitlab.com/{usuario}/{proyecto}/commit/%H"› ver commit • ‹/a› %s ‹/li›' --reverse | grep "#changelog"
o agrupándolos por usuario:
git shortlog
o mostrando también el identificador corto de cada commit:
git log {etiqueta} HEAD --oneline
o filtrando la corrección de errores:
git log {etiqueta} HEAD --grep Corrige
También se puede recurrir a herramientas más refinadas:
- git-changelog, es configurable para definir adecuadamente los filtros de los mensajes.
- gitchangelog, es compatible con Python 2 y 3 para Linux, Mac y Windows. Está publicado en PyPI y también es configurable.
- git-extras, paquete para Linux (Debian, Ubuntu) que añade a Git un comando
git changelog
(leer manual) entre otros muchos comandos. - ReadmeGen, en este caso es un programa PHP que también busca mensajes con un patrón específico para extraerlos y agruparlos.
- Y si se utiliza GitLab como respositorio, se puede probar este código para generar el archivo CHANGELOG.
Última revisión: 22/07/2020
Dejar un comentario
¿Quieres unirte a la conversación?Siéntete libre de contribuir!