¿Por qué son importantes los mensajes de un commit?h1

Los mensajes de commit son mucho más que simples notas: son la documentación viva de nuestros proyectos. Las razones por las que son fundamentales incluyen:

• 📚 Comunican el “por qué”: Un diff muestra los cambios, pero el mensaje explica el contexto y la razón detrás de ellos.
• 🙋🏻‍♂️ Facilitan la colaboración: Mensajes claros ayudan a futuros desarrolladores (incluido al autor) a entender el historial del proyecto.
• 🛠️ Mejoran herramientas como git log, git blame, y git rebase: Un historial bien estructurado agiliza la revisión y el mantenimiento.
• 🤝🏻 Contribución en proyectos OpenSource: Si uno desea colaborar, es importante seguir estándares acordados por la gran mayoría de desarrolladores.

Las 7 reglas de oroh1

1. Separar el asunto (subject) del cuerpo (body) con una línea en blancoh2

• Asunto: Breve resumen (ej: “Corregir error de autenticación”).
• Cuerpo: Detalles y contexto (opcional para cambios simples).

Ejemplo:

Optimizar carga de imágenes

Se redujo el tamaño de las imágenes usando WebP en lugar de PNG,
mejorando el tiempo de carga en un 40%.

Si se analiza la estructura, es muy similar a un correo electrónico. Esto es porque git permite enviar emails con el contenido de los mensajes de los commits a los diversos colaboradores del proyecto.

2. Limitar el asunto a 50 caracteresh2

• Objetivo: Ser conciso y legible en herramientas como git log --oneline.
• Límite máximo: 72 caracteres (evita truncamiento en interfaces como GitHub).

Si tu explicación supera esa cantidad de caracteres, deberías separar tus commit en commits más pequeños. Es importante tener en consideración el concepto de commits atómicos.

3. Capitalizar el asuntoh2

• Correcto ✅: “Agregar validación de formulario”.
• Incorrecto ❌: “agregar validación de formulario”.

4. No usar punto final en el asuntoh2

• Correcto ✅: “Actualizar documentación de la API”.
• Incorrecto ❌: “Actualizar documentación de la API.”.

5. Usar modo imperativo en el asuntoh2

Si te cuesta darte cuenta de cómo deberías escribir el verbo, puedes seguir la siguiente fórmula:

• Fórmula: “Si se aplica, este commit [verbo en infinitivo]…”.
• Ejemplos:
  • Correcto ✅: “Corregir error en cálculo de impuestos” (imperativo: “Corregir”).
  • Incorrecto ❌: “Corrección de error en cálculo de impuestos” (indicativo).

6. Limitar el cuerpo a 72 caracteres por líneah2

• Objetivo: Mantener legibilidad en terminales y herramientas de revisión.
• Herramientas: Configurar editores (Vim, VS Code) para ajustar automáticamente.

7. Enfocar el cuerpo en el “qué” y “por qué”, no en el “cómo”h2

• Qué: Problema resuelto o funcionalidad agregada.
• Por qué: Razón del cambio (ej: “El método anterior causaba lentitud en X”).
• Evitar detalles técnicos: El código ya muestra el “cómo”; usar comentarios en el código si es necesario.

Estructura de ejemploh1

Resumir el cambio en menos de 50 caracteres

Texto explicativo detallado. Enfocarse en el contexto y la motivación,
no en la implementación. Usar líneas de 72 caracteres.

- Listas con viñetas son útiles para claridad.
- Referenciar issues o PRs al final (ej: Fixes #123, Ref #456).

Buenas prácticash1

Commits atómicosh2

Un commit por funcionalidad/corrección (evitar mezclar cambios no relacionados).

Herramientas de línea de comandosh2

Preferir Git CLI sobre IDEs para mayor control (ej: git commit sin -m para mensajes largos).

Plantillash2

Usar git config commit.template para estandarizar mensajes en equipos.

Ejemplo real (Bitcoin Core)h2

Simplify serialize.h's exception handling

Remove redundant 'state' and 'exceptmask' variables. Direct exception
throwing replaces convoluted error handling, reducing code complexity
and potential bugs.

Estándares de la industria: Conventional Commitsh1

Muchas empresas y proyectos open source adoptan el estándar Conventional Commits para estructurar sus mensajes de commit de manera consistente.

Estructura básicah2

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Tipos comunesh2

• feat: Nueva funcionalidad
• fix: Corrección de errores
• refactor: Refactorización de código
• docs: Cambios en documentación
• style: Cambios de formato (espacios, puntos y comas, etc.)
• test: Agregar o modificar tests
• chore: Tareas de mantenimiento
• ci: Cambios en CI/CD
• build: Cambios en el sistema de build

Ejemplosh2

feat(auth): add OAuth2 login support

fix(api): resolve memory leak in user sessions

docs(readme): update installation instructions

refactor(utils): simplify date formatting functions

Herramientas útilesh1

Configuración de Gith2

# Configurar plantilla de commit
git config --global commit.template ~/.gitmessage

# Configurar editor preferido
git config --global core.editor "code --wait"

Ejemplo de plantilla (~/.gitmessage)h2

# <type>[optional scope]: <description>
#
# [optional body]
#
# [optional footer(s)]

# Tipos: feat, fix, docs, style, refactor, test, chore
# Mantener líneas de asunto bajo 50 caracteres
# Usar modo imperativo: "add" no "added" ni "adds"
# Separar asunto del cuerpo con línea en blanco
# Explicar qué y por qué vs. cómo

Herramientas de CLIh2

Commitizenh3

npm install -g commitizen
npm install -g cz-conventional-changelog

# Configurar
echo '{ "path": "cz-conventional-changelog" }' > ~/.czrc

# Usar
git cz

Commitlinth3

npm install -g @commitlint/cli @commitlint/config-conventional

# Configurar hook
echo "module.exports = {extends: ['@commitlint/config-conventional']}" > commitlint.config.js

Beneficiosh1

• Historial legible: Facilita navegación con git log, git blame, etc.
• Mantenibilidad: Reduce tiempo en depuración y entendimiento de cambios antiguos.
• Colaboración eficiente: Mensajes claros agilizan revisiones de código (PRs) y onboarding de nuevos desarrolladores.
• Automatización: Permite generar changelogs automáticos y versionado semántico.
• Profesionalismo: Demuestra atención al detalle y consideración por el equipo.

Comandos Git útiles para el historialh1

# Ver historial en una línea
git log --oneline

# Ver historial con gráfico
git log --graph --oneline --all

# Buscar en mensajes de commit
git log --grep="fix"

# Ver cambios de un archivo específico
git log --follow -- archivo.js

# Ver estadísticas de commits
git shortlog -s -n

Conclusiónh1

Escribir buenos mensajes de commit es una habilidad fundamental para cualquier desarrollador. No solo mejora la experiencia de desarrollo personal, sino que también facilita la colaboración en equipo y el mantenimiento a largo plazo de los proyectos. La forma de escribir varían de organización a organización, pero es importante seguir las reglas de oro y los estándares de la industria para mejorar la colaboración en equipo.

Un buen commit message es una inversión en el futuro de tu proyecto, sino de lo contrario pan para hoy, pero no para mañana.

Referenciash1

• Conventional Commits
• Commitizen
• Commitlint
• Git Commit Message Conventions