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:%so 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 shortlogo mostrando también el identificador corto de cada commit:
git log {etiqueta} HEAD --onelineo filtrando por los mensajes de corrección de errores:
git log {etiqueta} HEAD --grep CorrigeTambié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.
Referencias
Última revisión: 12/10/2022
Dejar un comentario
¿Quieres unirte a la conversación?Siéntete libre de contribuir!