Mensajes de commit claros y consistentes

Los mensajes de commit son una parte fundamental de cualquier flujo de trabajo con Git. Aunque a menudo se subestima su importancia, escribir mensajes de commit claros y consistentes mejora significativamente la colaboración, facilita el mantenimiento del código y proporciona una documentación valiosa sobre la evolución del proyecto.

¿Por qué son importantes los mensajes de commit?

Un buen mensaje de commit sirve para múltiples propósitos:

1. Comunica el cambio: Explica qué cambió y por qué
2. Facilita la revisión de código: Ayuda a los revisores a entender el propósito del cambio
3. Documenta la historia: Crea un registro útil de la evolución del proyecto
4. Ayuda en la depuración: Facilita encontrar cuándo y por qué se introdujo un cambio específico
5. Automatiza procesos: Permite la generación automática de notas de lanzamiento y versiones

Como dijo Peter Hutterer: "Los mensajes de commit son una carta a tu futuro yo". Cuando revisas el código meses o años después, agradecerás haber escrito mensajes claros y descriptivos.

Anatomía de un buen mensaje de commit

Un mensaje de commit efectivo generalmente sigue esta estructura:

<tipo>(<ámbito>): <asunto>

<cuerpo>

<pie>

Asunto (obligatorio)

La primera línea del mensaje de commit debe:

• Ser concisa (50 caracteres o menos)
• Comenzar con un verbo en imperativo ("Añade", "Corrige", "Actualiza")
• No terminar con punto
• Describir qué hace el cambio, no cómo lo hace

Ejemplos:

Añade validación de formulario de contacto
Corrige error de cálculo en el total del carrito
Actualiza dependencia React a v18.0

Cuerpo (opcional)

El cuerpo del mensaje proporciona contexto adicional:

• Separado del asunto por una línea en blanco
• Explica el "por qué" detrás del cambio
• Describe problemas que resuelve
• Menciona efectos secundarios o consecuencias
• Limita cada línea a 72 caracteres

Ejemplo:

Refactoriza sistema de autenticación

- Reemplaza la autenticación basada en sesiones por tokens JWT
- Mejora la seguridad al implementar expiración de tokens
- Reduce la carga en la base de datos al eliminar consultas frecuentes

Este cambio es necesario para soportar la nueva API móvil y
mejorar el rendimiento en situaciones de alta carga.

Pie (opcional)

El pie contiene metadatos como:

• Referencias a issues o tickets: Fixes #123
• Cambios importantes: BREAKING CHANGE: La API v1 ya no es compatible
• Co-autores: Co-authored-by: Nombre <email@ejemplo.com>

Convención de Conventional Commits

Conventional Commits es una especificación para añadir significado semántico a los mensajes de commit. Sigue esta estructura:

<tipo>[ámbito opcional]: <descripción>

[cuerpo opcional]

[pie opcional]

Tipos comunes

• feat: Nueva característica
• fix: Corrección de errores
• docs: Cambios en documentación
• style: Cambios que no afectan el significado del código (espacios, formato, etc.)
• refactor: Refactorización de código
• perf: Mejoras de rendimiento
• test: Añadir o corregir pruebas
• build: Cambios en el sistema de compilación o dependencias
• ci: Cambios en la configuración de CI/CD
• chore: Tareas rutinarias que no modifican código ni pruebas

Ejemplos de Conventional Commits

feat(auth): implementa inicio de sesión con Google

fix(cart): corrige cálculo incorrecto del total con descuentos

docs(readme): actualiza instrucciones de instalación

refactor(api): simplifica manejo de errores en endpoints

test(user): añade pruebas para validación de correo electrónico

feat(api)!: cambia formato de respuesta de JSON a XML

BREAKING CHANGE: Los clientes necesitarán actualizar para manejar XML

Buenas prácticas para mensajes de commit

1. Haz commits atómicos

Cada commit debe representar un cambio lógico único y completo. Esto facilita:

• Entender cada cambio individualmente
• Revertir cambios específicos si es necesario
• Realizar cherry-picks entre ramas

2. Separa cambios de formato y contenido

Si necesitas reformatear código y añadir funcionalidades, hazlo en commits separados:

style: aplica formato consistente al código
feat: implementa nueva funcionalidad de búsqueda

3. Usa tiempo presente

Escribe los mensajes en tiempo presente, como si el commit estuviera aplicando los cambios:

• ✅ "Añade función de búsqueda"
• ❌ "Añadió función de búsqueda"
• ❌ "Añadiendo función de búsqueda"

4. No uses mensajes genéricos

Evita mensajes que no proporcionan información útil:

• ❌ "Arregla errores"
• ❌ "Actualiza código"
• ❌ "WIP" (Work In Progress)
• ❌ "Cambios menores"

5. Referencia issues y tickets

Vincula tus commits con el sistema de seguimiento de problemas:

feat(auth): implementa recuperación de contraseña

Closes #123

6. Menciona cambios importantes

Destaca claramente los cambios que rompen compatibilidad:

feat!: elimina soporte para Internet Explorer

BREAKING CHANGE: Esta versión ya no es compatible con IE11.
Los usuarios necesitarán actualizar a un navegador moderno.

Herramientas para mejorar los mensajes de commit

Plantillas de commit

Puedes crear una plantilla para tus mensajes de commit:

1. Crea un archivo .gitmessage:

# <tipo>(<ámbito>): <asunto>
# |<----  Usar máximo 50 caracteres  ---->|

# Explicación detallada, si es necesaria:
# |<----   Tratar de limitar cada línea a 72 caracteres   ---->|

# Incluir motivación para el cambio y contrastar con el comportamiento anterior
# - Problema 1 resuelto
# - Problema 2 resuelto

# Mencionar issues relacionados
# Resolves: #123
# See also: #456, #789

2. Configura Git para usar la plantilla:

git config --global commit.template ~/.gitmessage

Hooks de Git

Puedes usar Git hooks para validar los mensajes de commit:

# .git/hooks/commit-msg
#!/bin/sh

commit_msg=$(cat "$1")
pattern='^(feat|fix|docs|style|refactor|perf|test|build|ci|chore)(\([a-z0-9]+\))?: .{1,50}$'

if ! echo "$commit_msg" | head -1 | grep -qE "$pattern"; then
  echo "ERROR: El mensaje de commit no sigue el formato de Conventional Commits"
  echo "Debe ser: <tipo>(<ámbito>): <asunto>"
  exit 1
fi

Herramientas de línea de comandos

• Commitizen: CLI que te guía para crear mensajes de commit siguiendo convenciones
• commitlint: Linter para mensajes de commit
• git-cz: Herramienta interactiva para crear commits

Automatización basada en mensajes de commit

Los mensajes de commit bien estructurados permiten automatizar varios procesos:

Versionado semántico automático

Herramientas como semantic-release pueden determinar automáticamente la próxima versión basándose en los tipos de commit:

• fix: incrementa la versión PATCH (1.0.0 → 1.0.1)
• feat: incrementa la versión MINOR (1.0.0 → 1.1.0)
• feat! o commits con BREAKING CHANGE: incrementa la versión MAJOR (1.0.0 → 2.0.0)

Generación de changelogs

Los mensajes de commit bien estructurados facilitan la generación automática de changelogs:

# Changelog

## [1.1.0] - 2025-04-28

### Added
- Implementa inicio de sesión con Google (#123)
- Añade modo oscuro a la interfaz de usuario (#145)

### Fixed
- Corrige cálculo incorrecto del total con descuentos (#156)
- Soluciona problema de rendimiento en la carga de imágenes (#162)

### Documentation
- Actualiza instrucciones de instalación (#170)

Mensajes de commit en equipos

Establecer estándares de equipo

Documenta las convenciones de mensajes de commit en un archivo CONTRIBUTING.md:

• Formato requerido
• Ejemplos de buenos y malos mensajes
• Cómo referenciar issues y tickets
• Herramientas recomendadas

Revisión de código

Durante las revisiones de código, evalúa también la calidad de los mensajes de commit:

• ¿El mensaje explica claramente el cambio?
• ¿Sigue las convenciones del equipo?
• ¿Proporciona contexto suficiente?

Integración con flujos de trabajo

Integra la validación de mensajes de commit en tu CI/CD:

# .github/workflows/validate-commits.yml
name: Validate Commit Messages
on: [pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
        with:
          fetch-depth: 0
      - uses: wagoid/commitlint-github-action@v4

Conclusión

Los mensajes de commit claros y consistentes son una inversión en la mantenibilidad y colaboración a largo plazo de tu proyecto. Aunque puede parecer un detalle menor, el impacto acumulativo de buenos mensajes de commit es significativo:

• Facilitan la comprensión de la historia del proyecto
• Mejoran la colaboración entre desarrolladores
• Permiten automatizar procesos como versionado y generación de changelogs
• Proporcionan documentación valiosa integrada en el flujo de trabajo

Adoptar convenciones como Conventional Commits y fomentar buenas prácticas en tu equipo creará un historial de proyecto más útil y profesional, beneficiando tanto a los colaboradores actuales como futuros.