Mensaje de confirmación de Git: Las reglas, ejemplos y convenciones

Por qué es importante el mensaje de confirmación de Git

Un mensaje de confirmación explica tus cambios a cualquiera que lea el código más adelante, incluido tu yo futuro.

Dentro de tres meses, no recordarás por qué refactorizaste ese canal de datos o por qué cambiaste de pandas a polars para una operación específica. Tu mensaje de confirmación es el único registro de tu razonamiento. Sin él, te ves obligado a hacer conjeturas o a rebuscar en los hilos de Slack y los tickets de JIRA.

Aquí hay un par de razones más concretas por las que los mensajes de confirmación de git son importantes.

Las revisiones de código avanzan más rápido con mensajes de confirmación claros. Tu revisor puede analizar el mensaje, comprender la intención y centrarse en si la implementación coincide. Los mensajes vagos obligan a los revisores a realizar ingeniería inversa de tu pensamiento a partir de la diferencia.

La depuración también resulta más fácil. Cuando aparezca un error, utilizarás git log o git blame para rastrear cuándo se introdujo el código problemático. Un mensaje como «corregir error de autenticación» no dice nada. Un mensaje como «corregir la comprobación de caducidad del token en el middleware de autenticación» te indica directamente cuál es el problema.

La colaboración en equipo depende de un historial legible. Cuando alguien se une a tu proyecto o continúa donde tú lo dejaste, leerá los commits para comprender cómo ha evolucionado el código base. Los mensajes claros convierten tu historial de Git en documentación que realmente resulta útil.

La conclusión es que escribir un mensaje descriptivo para una confirmación lleva entre 15 y 30 segundos. Pero te ahorra horas de confusión más adelante.

Principios básicos de un buen mensaje de confirmación en Git

Los buenos mensajes de confirmación siguen unos principios sencillos, nada más.

Escribe para los lectores del futuro.

Tu mensaje de confirmación no es para ti ahora mismo, sino para quien lo lea dentro de seis meses.

Esa persona podría ser un nuevo miembro del equipo que intenta comprender por qué el código base funciona de una determinada manera. Podrías ser tú, tratando de recordar por qué tomaste una decisión concreta. En cualquier caso, no tendrán el contexto que tú tienes hoy.

Céntrate en la intención y el razonamiento, no solo en lo que ha cambiado. El diff muestra lo que ha cambiado. Tu mensaje debe explicar por qué ha cambiado y qué problema resuelve.

Sé claro y conciso.

Los mensajes cortos y descriptivos son más fáciles de leer cuando estás revisando docenas de confirmaciones.

Un mensaje como «añadir caché» es ambiguo. Un mensaje como «añadir caché Redis para las respuestas API» te indica exactamente lo que ha ocurrido. Puedes leerlo en git log --oneline y saber inmediatamente qué hace el commit.

El asunto del correo electrónico debe responder a la siguiente pregunta: ¿qué hace este commit? Si necesitas más de 50-60 caracteres para responder a eso, probablemente estés realizando demasiados cambios a la vez.

Sé coherente.

La coherencia en todo tu repositorio hace que el historial sea predecible y más fácil de analizar.

Cuando todas las confirmaciones siguen el mismo formato, puedes revisar rápidamente el historial. Sabes dónde buscar el tipo de cambio, el alcance y la descripción. Los equipos que aplican formatos coherentes también pueden automatizar tareas como generar registros de cambios o filtrar confirmaciones por tipo.

Elige un estilo y mantente fiel a él. Si tu equipo utiliza imperativos en tiempo presente, no cambies aleatoriamente al tiempo pasado.

Explica qué y por qué (no cómo).

El código muestra cómo resolviste el problema. Tu mensaje de confirmación debe explicar cuál era el problema y por qué elegiste esta solución.

No escribas «refactorizar load_data() para usar la comprensión de listas en lugar del Bucle for». Escribe «acelerar la carga de datos en un 40 % para archivos CSV de gran tamaño». El primer mensaje describe el cambio en el código. El segundo explica el impacto.

Añade contexto cuando ayude a los futuros lectores a comprender tu decisión. Si has probado tres enfoques diferentes antes de decidirte por este, menciónalo. Si hay algún informe de error o decisión de diseño relacionado, haz referencia a él.

La estructura de un mensaje de confirmación de Git

La mayoría de los mensajes de confirmación de Git siguen una estructura estándar de tres partes: línea de asunto, cuerpo y pie de página.

Asunto

El asunto es un resumen de una línea que aparece en git log --oneline y en las listas de solicitudes de extracción.

Si es posible, no superes los 50 caracteres, y como máximo 72. Este límite garantiza que el mensaje se muestre correctamente en la salida del terminal y en la interfaz de usuario de GitHub sin que se corte. Si no puedes resumir en 50 caracteres, probablemente estés intentando describir demasiados cambios en una sola confirmación.

Utiliza el modo imperativo: escribe «añadir función» en lugar de «añadido función» o «añade función». Piensa en ello como completar la frase «Si se aplica, este compromiso...». Por lo tanto, «Si se aplica, este commit añadirá el almacenamiento en caché de Redis» se lee con naturalidad, mientras que «Si se aplica, este commit añade el almacenamiento en caché de Redis» no.

Ejemplos:

• fix null pointer exception in data loader

• add caching layer for API responses

• remove deprecated pandas functions

Cuerpo (cuando sea necesario)

Omite el cuerpo para cambios sencillos. Si el asunto explica completamente la confirmación, ya está todo listo.

Añade un cuerpo cuando necesites explicar por qué has realizado el cambio o proporcionar contexto que ayude a los futuros lectores. Deja una línea en blanco entre el asunto y el cuerpo: Git la utiliza para separar las dos partes.

El cuerpo debe responder a preguntas como: ¿Qué problema resuelve esto? ¿Por qué elegiste este enfoque? ¿Existen efectos secundarios o limitaciones? ¿Consideraste otras soluciones?

Divide las líneas en 72 caracteres para que el texto sea legible en la salida del terminal. La mayoría de los editores de texto pueden hacerlo automáticamente.

Ejemplo:

add Redis caching for API responses

API response times were hitting 2-3 seconds for repeated queries.
Added Redis with 5-minute TTL to cache query results. This drops
response time to ~50ms for cached queries.

Considered using in-memory cache but Redis lets us scale horizontally
if needed.

Pie de página (opcional)

Utiliza el pie de página para hacer referencia a problemas relacionados, solicitudes de extracción o cambios importantes.

Si tu confirmación soluciona un problema de GitHub, añade Fixes #123 o Closes #456 en el pie de página. GitHub cerrará automáticamente el problema cuando se fusione la confirmación. Para cambios importantes, añade BREAKING CHANGE: seguido de una descripción de lo que ha cambiado y cómo migrar.

Ejemplo:

remove support for Python 3.7

Python 3.7 reached end-of-life in June 2023. This commit drops
support and updates minimum version to Python 3.8.

BREAKING CHANGE: Python 3.7 users must upgrade to 3.8 or later.
Closes #789

No necesitas un pie de página para la mayoría de las confirmaciones, solo cuando enlazas con referencias externas o marcas cambios importantes.

Tipos comunes de mensajes de confirmación de Git y cuándo utilizarlos

Muchos proyectos utilizan prefijos de tipo de confirmación para clasificar los cambios de un vistazo.

No es necesario que memorices una lista estricta de etiquetas. El objetivo es ayudar a los lectores a identificar rápidamente qué tipo de cambio se ha producido sin tener que leer todo el diff.

Aquí hay cuatro categorías que debes tener en cuenta:

• Los cambios en las características introducen nuevas funcionalidades. Utiliza prefijos como feat: o add: cuando crees algo nuevo: un nuevo punto final de API, una función de procesamiento de datos o una característica orientada al usuario. Ejemplo: feat: add CSV export for analysis results.

• Las correcciones de errores resuelven los problemas existentes. Utiliza « fix: » (No lo hagas así) cuando corrijas un comportamiento que no ha funcionado como se esperaba. Esto podría ser cualquier cosa, desde una excepción de puntero nulo hasta cálculos incorrectos en tu modelo. Ejemplo: fix: handle missing values in preprocessing pipeline.

• Actualizaciones de la documentación mejora los comentarios del código, los archivos README o la documentación en línea. Utiliza « docs: » cuando no cambies el funcionamiento del código, sino que solo lo expliques mejor. Ejemplo: docs: add usage examples for data loader class.

• El trabajo de refactorización y mantenimiento mejora la estructura del código sin cambiar su comportamiento. Utiliza refactor: cuando reorganices el código para que sea más limpio y fácil de mantener. Utiliza chore: para tareas rutinarias como actualizar dependencias o cambiar configuraciones de compilación. Ejemplos: refactor: extract validation logic into separate module o chore: update pandas to 3.0.0.

Elige el tipo que mejor describa tu cambio y sigue adelante: la coherencia es más importante que elegir la etiqueta «perfecta».

Reglas para escribir un mejor mensaje de confirmación de Git

Aquí tienes una lista de reglas que harán que tus mensajes de confirmación sean más útiles.

• Mantén el asunto por debajo de los 50 caracteres. Esto garantiza que se muestre correctamente en git log --oneline, la lista de confirmaciones de GitHub y la salida del terminal sin truncarse. Si no puedes resumir tu mensaje en 50 caracteres, intenta que no supere los 72.

• Usa el modo imperativo. Escribe «añadir función» en lugar de «función añadida» o «añade función». El asunto del correo electrónico debe completar la frase «Si se aplica, esta confirmación...». Por lo tanto, «Si se aplica, este commit añadirá almacenamiento en caché» se lee correctamente.

• Separa el asunto y el cuerpo con una línea en blanco. Git utiliza esta línea en blanco para distinguir entre el resumen y la explicación detallada. Sin él, las herramientas de Git podrían mostrar tu mensaje de forma incorrecta.

• Omite el punto al final de la línea de asunto. Estás ahorrando caracteres y, de todos modos, el asunto no es una frase completa. Escribe fix null pointer in loader en lugar de fix null pointer in loader.

• Escribe en mayúscula la primera palabra del asunto. Escribe Add caching for API calls en lugar de add caching for API calls. Esto mantiene tu historial de confirmaciones con un aspecto coherente y profesional.

• Utiliza el cuerpo para explicar por qué, no qué. El diff muestra lo que ha cambiado. Tu organismo debe explicar los motivos del cambio, los enfoques alternativos que has considerado y las concesiones que has hecho.

• Ajustar el texto del cuerpo a 72 caracteres. Esto evita problemas de ajuste de línea en la salida del terminal y mantiene tus mensajes de confirmación legibles en diferentes herramientas.

• Haz que cada confirmación sea atómica. Un cambio lógico por cada confirmación. Si estás corrigiendo un error y refactorizando código, divídelos en dos confirmaciones con mensajes separados.

Ejemplos de un buen mensaje de confirmación de Git

A continuación, se muestran ejemplos reales que ilustran cómo deben ser los mensajes de confirmación adecuados para diferentes situaciones.

Una solución sencilla

fix: handle NaN values in feature engineering

The preprocessing pipeline crashed when encountering NaN values
in the 'age' column. Added fillna() with median imputation before
scaling features.

Esto funciona porque identifica el problema (fallos NaN), explica dónde se produjo (canalización de preprocesamiento, columna de edad) y describe la solución (imputación de la mediana).

Una nueva función

feat: add model performance tracking to MLflow

Added automatic logging of model metrics, parameters, and artifacts
to MLflow after each training run. This replaces our manual CSV
logging and makes experiment comparison much easier.

Metrics tracked: accuracy, precision, recall, F1 score
Training time also logged for performance monitoring.

Las buenas confirmaciones de características explican lo que has creado, por qué es útil y cualquier detalle que ayude a los lectores a comprender el alcance.

Una refactorización

refactor: split data_loader.py into separate modules

Moved dataset classes to datasets.py, transformation logic to
transforms.py, and utility functions to utils.py. The original
file was 800+ lines and hard to navigate.

No behavior changes - all tests still pass.

Los mensajes de refactorización deben dejar claro que no has cambiado la funcionalidad, solo la estructura. La frase «todas las pruebas siguen superándose» tranquiliza a los revisores.

Actualización de la documentación

docs: add examples for custom loss functions

Previous documentation showed only built-in loss functions.
Added three examples: weighted cross-entropy, focal loss, and
custom regression loss with L1 regularization.

Each example includes code and explanation of when to use it.

Las confirmaciones de documentación deben explicar qué has documentado y por qué era necesario.

Referencia a un problema o ticket

fix: prevent memory leak in batch processing

Large datasets caused memory usage to grow unbounded during batch
processing. The issue was holding references to processed batches
in the results list.

Changed to yield results instead of accumulating them in memory.
Memory usage now stays constant regardless of dataset size.

Fixes #247

Cuando hagas referencia a un problema, incluye suficiente contexto para que alguien pueda entender la solución sin tener que hacer clic en el ticket. La opción « Fixes #247 » (Cerrar automáticamente este problema cuando se fusione esta confirmación) situada en la parte inferior indica a GitHub que cierre automáticamente el problema cuando se fusione esta confirmación.

Todos los ejemplos siguen el mismo patrón: comienza con lo que ha cambiado, explica por qué, añade contexto que ayude a los futuros lectores y haz referencia a cuestiones relacionadas cuando sea pertinente.

Los commits convencionales como estándar para los mensajes de commit de Git

Los commits convencionales son un formato popular que añade estructura a los mensajes de commit mediante un sencillo patrón de prefijo.

Formato básico

El formato es el siguiente: type(scope): description.

El tipo describe el tipo de cambio que estás realizando: feat para funciones, fix para correcciones de errores, docs para documentación, refactor para reestructuración de código, etc. Elámbito es opcional y especifica qué parte del código base ha cambiado, como (auth) o (api). La descripción « » explica lo que hiciste.

Ejemplos:

feat(api): add endpoint for batch predictions
fix(auth): prevent token expiration edge case
docs(readme): add installation instructions for Windows
refactor(data): extract validation logic to separate module

Solo ten en cuenta que se trata de una convención, no de un requisito. A Git no le importa si utilizas este formato. En gran medida, se trata de una decisión del equipo sobre cómo estructurar tus mensajes para garantizar la coherencia y las herramientas.

Cuándo son útiles las confirmaciones convencionales

Los equipos que automatizan los procesos de lanzamiento obtienen el máximo valor de las confirmaciones convencionales.

Las herramientas pueden analizar tu historial de confirmaciones y generar automáticamente registros de cambios. Cuando etiquetas una versión, la herramienta analiza las confirmaciones desde la última versión, las agrupa por tipo (feat, fix, docs) y crea un registro de cambios formateado. Esto ahorra el trabajo manual de rastrear qué ha cambiado entre versiones.

Las confirmaciones convencionales también admiten la automatización del versionado semántico. Si todas tus confirmaciones desde la última versión están corregidas, la herramienta aumenta la versión del parche (1.2.3 → 1.2.4). Si has añadido funciones, la versión menor aumenta (1.2.3 → 1.3.0). Los cambios importantes provocan un salto significativo en la versión (1.2.3 → 2.0.0).

Pero si tu equipo no utiliza lanzamientos automatizados ni generación de registros de cambios, las confirmaciones convencionales pueden resultar excesivas. La estructura ayuda más a las máquinas que a los humanos, así que tenlo en cuenta.

Errores comunes que debes evitar en los mensajes de confirmación de Git

Incluso los programadores experimentados a veces cometen errores al escribir mensajes de confirmación, pero eso tiene más que ver con la pereza que con la falta de conocimientos.

Aquí tienes un par de errores que debes evitar.

Mensajes vagos o genéricos

Mensajes como «corregir error» o «actualizar código» no aportan nada a los futuros lectores.

Cuando buscas un cambio específico en git log, revisas docenas de confirmaciones. Un mensaje que dice «corregir error» te obliga a abrir el diff y leer el código para entender qué se ha corregido. Un mensaje que dice «corregir puntero nulo en el preprocesamiento de datos» te indica inmediatamente si se trata de la confirmación que estás buscando.

Los mensajes genéricos hacen perder tiempo a todo el mundo. Si no recuerdas lo que has cambiado lo suficientemente bien como para escribir un mensaje específico, probablemente no deberías realizar la confirmación todavía.

Mezcla de cambios no relacionados

Cada confirmación debe contener un único cambio lógico.

Cuando corriges un error y refactorizas código no relacionado en la misma confirmación, dificultas las revisiones de código y haces que git bisect sea inútil. Si ese commit introduce una regresión, alguien tendrá que desentrañar qué parte del cambio la ha causado. Si queréis revertir solo la corrección del error, no pueden: también revertirán la refactorización.

Siempre debes dividir los cambios en confirmaciones separadas. Corregir el error en una confirmación y refactorizar en otra. Cada confirmación debe ser algo que puedas revertir de forma independiente sin romper el código base.

Si ya has mezclado los cambios localmente, utiliza git add -p para preparar partes de los archivos por separado y confirmarlos en bloques lógicos.

Dejar mensajes sobre trabajos en curso

Los commits con mensajes como «WIP» o «temp fix» están bien a nivel local, pero no deberían llegar a la rama principal rama.

Antes de fusionar tu rama de características, limpia tu historial de confirmaciones. Eliminar WIP se convierte en algo significativo con mensajes adecuados. Reescribe «asdf» y «intentando algo» en descripciones que expliquen lo que realmente hiciste.

Utiliza git rebase -i para combinar confirmaciones, reescribir mensajes y reordenar los cambios antes de enviarlos. Tu equipo debería ver un historial claro de lo que ha cambiado y por qué, sin tener que leer todo tu proceso de depuración.

Mejores prácticas para equipos que utilizan mensajes de confirmación de Git

Si tu equipo quiere que el historial de Git sea realmente útil, necesitas coherencia. A continuación, se indican algunas prácticas recomendadas que debes seguir.

Acuerda un estilo común desde el principio. Decide si vas a utilizar confirmaciones convencionales, un formato personalizado o simplemente un conjunto de reglas básicas. Elige un enfoque y aplícalo en todo el equipo. Cuando la mitad de tus confirmaciones dicen «feat: añadir característica» y la otra mitad dicen «Añadida nueva característica», tu historial se vuelve más difícil de examinar y la automatización puede fallar.

El estilo no importa tanto como que todos lo sigáis. Algunos equipos prefieren el imperativo en presente («añadir función»), otros utilizan el pasado («función añadida»). Ambos funcionan bien si se aplican de manera consistente.

Documenta tus convenciones en algún lugar accesible. Añade un archivo CONTRIBUTING.md a tu repositorio en el que expliques el formato de tus mensajes de confirmación con ejemplos. Inclúyelo en los documentos de incorporación para los nuevos miembros del equipo. Cuando alguien pregunte «¿cómo debo formatear esta confirmación?», remítele a la documentación en lugar de volver a explicárselo.

Tu documentación debe cubrir el formato básico que utilizas, cuándo añadir un cuerpo en lugar de limitarte a la línea de asunto, cómo hacer referencia a incidencias o tickets, y algunos ejemplos reales de tu repositorio.

Utiliza mensajes de confirmación durante las revisiones de código. Los mensajes de confirmación adecuados agilizan y centran las revisiones de las solicitudes de extracción. Los revisores pueden leer los mensajes de confirmación para comprender la progresión de los cambios antes de sumergirse en el código.

Al revisar, comprueba los mensajes de confirmación igual que compruebas el código. Si un mensaje es ambiguo o confuso, solicita que se vuelva a redactar antes de fusionarlo. Una solicitud de incorporación de cambios con compromisos claros es más fácil de revisar, más fácil de revertir si es necesario y más fácil de entender posteriormente.

Conclusión

Escribir un mensaje de confirmación claro lleva 30 segundos, pero ahorra horas de confusión más adelante.

Piensa en tu historial de confirmaciones como documentación que acompaña a tu código. Cuando escribes «corregir error» en lugar de «corregir puntero nulo en el preprocesamiento de datos», estás haciendo perder tiempo a todos los que lean esa confirmación más tarde, incluido tú mismo.

Trata tus mensajes de confirmación como si fueran código. Si no enviarías código descuidado y sin comentarios a producción, tampoco envíes mensajes de confirmación descuidados. Utiliza el modo imperativo, mantén las líneas de asunto por debajo de los 50 caracteres, explica el motivo en el cuerpo del mensaje cuando sea necesario y haz que cada compromiso sea atómico.

Ahora ya sabes cómo escribir mensajes de confirmación significativos. Para llevar tus habilidades al siguiente nivel, inscríbete en nuestro curso Git intermedio.