Tabla de contenidos

Referencias

Cuando contribuyes al repositorio de un proyecto Git y confirmas los cambios (commit) se requiere un mensaje que explique las modificaciones introducidas en el código.

Estos mensajes son importantes porque:

ayudan a entender los cambios sin tener que revisar el código;
facilitan y normalizan la navegación a través del historial de Git; y
filtran los cambios para facilitar la generación del archivo CHANGELOG (ver más abajo).

Un artículo de 2014 de Chris Beans evidenció esta importancia e introdujo siete reglas que debía tener un buen mensaje commit:

7 reglas para un buen mensaje commit

Separa el título del cuerpo con una línea en blanco.
Limita el título a 50 caracteres.
Inicia el título con letra mayúscula.
No termines el título con un punto.
Utiliza el modo imperativo en el título.
Limita el cuerpo a 72 caracteres.
Usa el cuerpo para explicar qué y por qué en lugar del cómo.

Visual Studio Code y otros entornos de desarrollo tienen en cuenta estas reglas para facilitar la redacción de estos mensajes; por ejemplo, con parámetros para configurar los límites de caracteres por línea.

Con estas reglas se han asentado entre la comunidad diferentes propuestas para escribir mensajes commit. Destacan:

Una guía para mensajes commit básicos;
los Commits convencionales (Conventional commits); o
gitm😜ji.

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ías crear un script para generar el archivo CHANGELOG según la Operación del asunto, 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 tendrías que repasarlo para eliminar o depurar los mensajes recogidos.

Usando Git puedes 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 lista 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 por los mensajes de corrección de errores:

git log {etiqueta} HEAD --grep Corrige

También puedes 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 utilizas GitLab como respositorio, puedes probar este código para generar el archivo CHANGELOG.