Commits y Conventional Commits

Por Jose R. Zapata

Ultima actualización: 20/Feb/2026

¿Qué es un Commit?

Un commit en Git es una forma de guardar (snapshot) el estado del código en un momento determinado. Es la unidad fundamental del versionamiento del código, permite tener un historial de un repositorio y representa un conjunto de cambios atómicos que se registran junto con:

• Un mensaje descriptivo: Explica qué se cambió y por qué.
• Metadatos automáticos: Autor, fecha, hora y un identificador único (hash SHA).
• Una referencia al estado anterior: Permite rastrear la evolución del código a lo largo del tiempo.

Cada commit es como un punto de control al que puedes regresar en cualquier momento. Si algo sale mal, puedes volver a un commit anterior y recuperar el estado funcional del proyecto.

¿Por qué importan los commits?

• Trazabilidad: Permiten saber quién hizo qué cambio y cuándo.
• Reversibilidad: Facilitan deshacer cambios problemáticos sin afectar el resto del trabajo.
• Colaboración: Proporcionan un historial compartido que todo el equipo puede consultar.
• Documentación viva: Un buen historial de commits cuenta la historia de cómo evolucionó el proyecto.

Buenas Prácticas para Commits

1. Commits Atómicos

Cada commit debe representar un solo cambio lógico. No mezcles múltiples funcionalidades o correcciones en un solo commit.

Mal ejemplo:

git commit -m "Agregar modelo de clasificación, corregir bug en preprocesamiento y actualizar README"

Buen ejemplo: Tres commits separados:

git commit -m "fix: corregir error en normalización de datos categóricos"
git commit -m "feat: agregar modelo de clasificación con Random Forest"
git commit -m "docs: actualizar README con instrucciones de entrenamiento"

2. Mensajes Claros y Descriptivos

Un buen mensaje de commit responde a la pregunta: ¿Qué hace este cambio y por qué?

• Usa el modo imperativo: “Agregar”, “Corregir”, “Eliminar” (no “Agregué” o “Se agregó”).
• Sé específico: Evita mensajes genéricos como “cambios”, “fix”, “update”, “wip”.
• Primera línea corta (< 72 caracteres): Resumen conciso del cambio.
• Cuerpo opcional: Si el cambio es complejo, agrega una explicación detallada después de una línea en blanco.

Mal ejemplo:

git commit -m "cambios"
git commit -m "fix bug"
git commit -m "actualización"

Buen ejemplo:

git commit -m "fix: corregir error de división por cero en cálculo de métricas

El cálculo de precision fallaba cuando no había predicciones positivas.
Se agrega validación para retornar 0.0 en ese caso."

3. Commits Frecuentes

No acumules muchos cambios para hacer un solo commit grande. Haz commits frecuentes con cambios pequeños y coherentes. Esto facilita:

• Identificar exactamente dónde se introdujo un bug (usando git bisect).
• Revisar el historial de forma más granular.
• Revertir cambios específicos sin perder trabajo adicional.

4. Revisar Antes de Hacer Commit

Antes de confirmar tus cambios:

• Usa git diff para revisar exactamente qué estás incluyendo.
• Usa git add -p para agregar cambios de forma selectiva (por fragmentos).
• No incluyas archivos innecesarios (configura correctamente .gitignore).
• No hagas commit de secretos, credenciales o datos sensibles.

5. No Reescribir el Historial Público

Evita usar git rebase, git commit --amend o git push --force en ramas compartidas. Esto puede causar problemas serios a tus compañeros de equipo.

Conventional Commits

Conventional Commits es una convención para escribir mensajes de commit de forma estandarizada. Proporciona un conjunto de reglas que hacen que el historial de commits sea más legible tanto para humanos como para herramientas automatizadas.

Estructura

<tipo>[alcance opcional]: <descripción>

[cuerpo opcional]

[notas de pie opcionales]

Tipos Principales

Breaking Changes

Cuando un cambio rompe compatibilidad, se indica con ! o con BREAKING CHANGE en el pie:

feat!: cambiar formato de respuesta de predicción a JSON-LD

BREAKING CHANGE: el endpoint /predict ahora retorna JSON-LD
en lugar de JSON plano. Los clientes deben actualizar su parser.

Ejemplos en Proyectos de Ciencia de Datos

# Repositorio
feat: agregar README.md con información del proyecto
docs: actualizar documentación de instalación y configuración
test: agregar tests unitarios para funciones de utilidad
chore: actualizar dependencias de numpy
chore: actualizar hooks de pre-commit

# Ingeniería de datos
feat: agregar extracción de datos desde API de ventas
fix: corregir manejo de valores nulos en columna precio
refactor: separar transformaciones de texto en módulo independiente

# Modelado
feat: implementar modelo XGBoost para predicción de churn
perf: reducir tiempo de entrenamiento usando paralelización
fix: corregir cálculo de feature de antigüedad del cliente

# Despliegue
feat: agregar health check endpoint al servicio de inferencia
ci: configurar reentrenamiento automático semanal
chore: actualizar imagen base a Python 3.11

# Experimentación
feat: agregar tracking de hiperparámetros con MLflow
docs: documentar análisis exploratorio de datos de usuarios

Commits y Agentes de Programación con IA

En la era de los agentes de programación con IA (como Claude Code, GitHub Copilot Agent, Cursor, entre otros), los mensajes de commit bien estructurados adquieren una importancia aún mayor. Estos agentes utilizan el historial de commits como contexto fundamental para entender el código y tomar decisiones.

¿Cómo usan los agentes los commits?

Los agentes de IA analizan los mensajes de commit para:

• Comprender la intención del cambio: Un mensaje claro como feat: agregar autenticación JWT le permite al agente entender qué se implementó y por qué, sin necesidad de analizar cada línea de código.
• Generar Pull Requests automáticos: Los agentes pueden crear descripciones de PR completas y precisas agrupando commits por tipo y alcance. Con conventional commits, pueden distinguir automáticamente entre nuevas funcionalidades, correcciones y cambios de documentación.
• Detectar el contexto del proyecto: Al leer el historial de commits, los agentes identifican patrones de desarrollo, tecnologías usadas y convenciones del equipo.
• Sugerir cambios relevantes: Con un historial claro, el agente puede proponer soluciones coherentes con la evolución del proyecto.
• Generar changelogs automáticos: Los conventional commits permiten generar automáticamente registros de cambios agrupados por tipo.

Ejemplo: De Commits a Pull Request

Supongamos que trabajas en una rama feature/modelo-churn con estos commits:

feat: agregar extracción de datos de comportamiento de usuarios
feat: implementar feature engineering para modelo de churn
test: agregar tests unitarios para nuevas features
feat: entrenar modelo XGBoost para predicción de churn
test: agregar tests de validación del modelo
docs: documentar métricas y decisiones de diseño del modelo

Un agente de IA puede leer estos commits y generar automáticamente un Pull Request como:

PR: Implementar modelo de predicción de churn

Resumen

• Se agrega pipeline completo para predicción de churn de usuarios
• Incluye extracción de datos, feature engineering y modelo XGBoost
• Cobertura de tests para features y validación del modelo

Cambios

• Datos: Nueva extracción de datos de comportamiento de usuarios
• Features: Feature engineering específico para churn
• Modelo: XGBoost entrenado con métricas documentadas
• Tests: Tests unitarios y de validación
• Documentación: Métricas y decisiones de diseño

Commits desordenados dificultan el trabajo del agente

Si en cambio los commits fueran:

git commit -m "cambios"
git commit -m "más cambios"
git commit -m "fix"
git commit -m "funciona"
git commit -m "ahora sí"

El agente no tiene contexto suficiente para:

• Entender qué se implementó.
• Agrupar los cambios de forma lógica.
• Generar una descripción de PR útil.
• Sugerir mejoras o detectar problemas.

Buenas prácticas para trabajar con agentes

• Usa Conventional Commits: Le das al agente una estructura predecible que puede interpretar automáticamente.
• Sé descriptivo en los mensajes: Más contexto en los commits significa mejores sugerencias del agente.
• Mantén commits atómicos: Facilita que el agente entienda cada cambio individual.
• Incluye el alcance (scope): Ayuda al agente a categorizar y agrupar cambios por área del proyecto.

Los agentes de IA son tan buenos como el contexto que les proporcionas. Un historial de commits bien escrito es una de las formas más efectivas de mejorar la calidad de la asistencia que estos agentes pueden ofrecer a tu equipo.

Herramientas Útiles

• vscode-conventional-commits: Extension para VS Code que valida los mensajes de commit siguiendo la convención de conventional commits.
• pre-commit hooks: Ejecuta validaciones automáticas antes de cada commit.

Referencias

• https://www.conventionalcommits.org
• https://www.freecodecamp.org/news/how-to-write-better-git-commit-messages/
• https://cbea.ms/git-commit/

Jose R. Zapata

• https://joserzapata.github.io/
• https://www.linkedin.com/in/jose-ricardo-zapata-gonzalez/