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}]

Cuerpo

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.

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 (Init) – para el primer commit de un respositorio.
    • 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 como config, 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"

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:'  ver commit •  %s  ' --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:

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 *