6.1.1.-Commits profesionales

6.1.1. Commits profesionales¶

Idea principal

Un commit profesional no es solo un mensaje para guardar cambios. Es una pieza de documentación técnica que explica qué se ha hecho, por qué se ha hecho y, cuando hace falta, qué impacto tiene ese cambio sobre el resto del proyecto.

Cuando un equipo trabaja con Git, el historial deja de ser una lista de copias de seguridad y pasa a convertirse en una herramienta de trabajo. Sirve para revisar cambios, depurar errores, entender decisiones técnicas, colaborar con otras personas y automatizar procesos como la generación de versiones o changelogs.

Lo importante en este tema es entender que un buen commit mejora la comunicación técnica del equipo. Dicho de forma sencilla: si dentro de dos meses vuelves a tu repositorio y entiendes rápidamente qué pasó en cada cambio, el historial está bien construido.

Código	Descripción
RA4	Optimiza código empleando las herramientas disponibles en el entorno de desarrollo.
CE f)	Se ha realizado el control de versiones integrado en el entorno de desarrollo.
CE h)	Se han utilizado repositorios remotos para el desarrollo de código colaborativo.
CE i)	Se han utilizado herramientas para la integración continua del código.

Definición

Un commit profesional es un registro atómico, claro y trazable de un cambio en el proyecto, redactado con una estructura y una intención que permitan comprenderlo tanto a personas como a herramientas automáticas.

Un buen mensaje de commit no describe solo el cambio. También ayuda a entender el contexto y la intención técnica que hay detrás.

1. Por qué importa escribir buenos commits¶

En un proyecto pequeño, un mensaje como cambios, update o arreglos ya resulta poco útil. En un proyecto real, directamente se convierte en ruido. El problema no es estético: afecta a la mantenibilidad, a la trazabilidad y a la capacidad del equipo para trabajar con seguridad.

En la práctica, un historial bien redactado permite:

localizar cuándo se introdujo un cambio;
revisar qué parte del sistema se tocó;
relacionar commits con incidencias, tareas o pull requests;
automatizar releases, versionado o generación de notas de versión;
colaborar mejor cuando varias personas trabajan sobre el mismo repositorio.

Regla rápida para clase

Si el mensaje no permite entender el cambio sin abrir el diff, probablemente todavía se puede mejorar.

2. Qué debe enseñar un commit al leerlo¶

Un alumnado técnico debe acostumbrarse a pensar que cada commit responde, como mínimo, a tres preguntas:

¿Qué se ha cambiado?
¿Dónde se ha cambiado?
¿Por qué era necesario hacerlo?

No siempre hace falta responder a las tres en una sola línea. Por eso los commits profesionales suelen tener varias partes. La idea no es escribir mensajes largos por obligación, sino escribir la información que realmente aporta valor.

3. Estructura básica de un mensaje de commit¶

La estructura más útil para empezar a trabajar en clase es esta:

Título: resumen corto del cambio.
Cuerpo: explicación del contexto o la razón del cambio.
Footer: metadatos, referencias a issues o avisos importantes.

tipo(ambito): resumen breve del cambio

Explicación del contexto, la motivación o el impacto.

Fixes: #123
BREAKING CHANGE: descripción del cambio incompatible

3.1. El título¶

El título debe poder leerse bien en un git log --oneline. Por eso conviene que sea breve, específico y directo. Una forma práctica de redactarlo es usar una acción clara:

fix(auth): corregir validación del token
docs: actualizar guía de instalación
feat(api): añadir filtro por estado

Lo que se busca aquí no es escribir bonito, sino transmitir información de alta señal.

3.2. El cuerpo¶

El cuerpo se utiliza cuando una línea no basta para entender el cambio. Es especialmente útil cuando:

el cambio no es evidente;
hay una decisión técnica detrás;
se modifica un comportamiento que puede afectar a otras partes;
interesa dejar constancia del motivo.

Un cuerpo útil explica el por qué. No hace falta repetir el diff con palabras.

El footer se reserva para datos estructurados. Por ejemplo:

referencias a incidencias;
cierres automáticos de issues;
coautoría;
avisos de ruptura de compatibilidad;
firmas o trazas de cumplimiento.

4. Convencional Commits como convención de trabajo¶

Una de las convenciones más usadas hoy en día es Conventional Commits. Su ventaja principal es que el historial resulta legible para el equipo y, al mismo tiempo, interpretable por herramientas automáticas.

La forma general es:

<tipo>(<ambito-opcional>): <descripcion>

También puede aparecer ! para marcar un cambio incompatible:

feat(api)!: renombrar el campo id a userId

Esta convención no resuelve solo un problema de estilo. En la práctica también facilita:

clasificar mejor los cambios;
generar changelogs;
inferir versiones semánticas;
aplicar validaciones con herramientas como commitlint.

5. Tipos de commit más habituales¶

No todos los equipos usan exactamente el mismo diccionario, pero conviene manejar un conjunto corto y estable. Para clase, estos tipos son suficientes:

Tipo	Cuándo usarlo	Ejemplo
`feat`	Se añade una funcionalidad nueva.	`feat(ui): añadir filtro por estado`
`fix`	Se corrige un error.	`fix(auth): evitar null pointer al cerrar sesión`
`docs`	Solo cambia la documentación.	`docs: corregir ejemplo de instalación`
`refactor`	Se reorganiza código sin cambiar el comportamiento esperado.	`refactor(parser): simplificar validación de tokens`
`test`	Se añaden o corrigen pruebas.	`test(api): cubrir error de autenticación`
`build`	Cambios de construcción, dependencias o empaquetado.	`build(deps): actualizar Kotlin a 2.1`
`ci`	Cambios en integración continua.	`ci: ejecutar tests en Java 21`
`chore`	Tareas de mantenimiento que no encajan mejor en otro tipo.	`chore(scripts): limpiar tareas temporales`
`perf`	Mejora de rendimiento.	`perf(cache): reducir consultas duplicadas`
`revert`	Revierte un commit anterior.	`revert: feat(api): añadir login social`

Criterio didáctico

Más importante que memorizar todos los tipos es usarlos con coherencia. Si el equipo define un vocabulario corto y lo mantiene, el historial gana claridad de forma inmediata.

6. El scope o ámbito del cambio¶

El scope indica la parte del proyecto afectada. Es opcional, pero resulta muy útil cuando el repositorio tiene varios módulos o capas.

Ejemplos razonables:

api
auth
ui
db
ci
docs

Ejemplos poco útiles:

misc
stuff
varios

En la práctica, el scope debe responder a esta pregunta: ¿qué zona del sistema se ha tocado?

7. Flujo de trabajo de un commit profesional¶

El proceso no consiste en programar mucho y al final lanzar un commit genérico. Lo más profesional es trabajar con cambios pequeños, coherentes y bien agrupados.

flowchart TD
    A[Modificar archivos] --> B[Revisar cambios con git diff]
    B --> C[Seleccionar solo lo que pertenece al cambio]
    C --> D[Redactar un mensaje claro]
    D --> E{Cumple la convención del proyecto?}
    E -- Sí --> F[Crear commit]
    E -- No --> D
    F --> G[Enviar a remoto y abrir PR]
    G --> H[CI valida el cambio]
    H --> I[Historial legible y trazable]

Este flujo ayuda a entender una idea importante: un commit profesional empieza antes de escribir el mensaje. Empieza cuando decides agrupar bien el cambio.

8. Relación con incidencias, repositorios remotos e integración continua¶

En proyectos colaborativos, los commits no viven aislados. Se conectan con incidencias, ramas remotas, revisiones de código y procesos automáticos.

8.1. Referencias a issues¶

Cuando el proyecto lo soporta, el footer puede enlazar o incluso cerrar incidencias automáticamente.

fix(login): corregir redirección tras expirar la sesión

Fixes: #42
Refs: #35

Esto mejora la trazabilidad porque permite seguir la relación entre problema, cambio aplicado y revisión posterior.

Qué significan Refs y Fixes

En este contexto, #42 o #35 hace referencia al identificador de una incidencia, tarea o issue dentro del repositorio. Dicho de forma sencilla, el símbolo # seguido de un número apunta a una tarjeta concreta del proyecto.

Refs: #ID significa que el commit está relacionado con esa incidencia, pero no necesariamente la resuelve. Se usa cuando quieres dejar constancia de que ese cambio forma parte del trabajo asociado a una tarea.

Fixes: #ID significa que el commit corrige o resuelve esa incidencia. En plataformas como GitHub, este tipo de palabra clave puede cerrar la issue automáticamente cuando el cambio llega a la rama principal, según el flujo de trabajo del proyecto.

Ejemplo práctico:

Refs: #35 se puede usar si el commit avanza una tarea, pero todavía faltan más cambios.
Fixes: #42 se puede usar si ese commit soluciona de verdad el problema descrito en la issue 42.

feat(auth): añadir validación del tiempo de expiración

Refs: #35

En este caso, el commit está relacionado con la tarea 35, pero no afirma que la haya terminado.

fix(auth): corregir cierre de sesión por renovación incorrecta del token

Fixes: #42

Aquí el mensaje indica que el problema de la issue 42 queda resuelto con ese cambio.

¿Cuándo usar una u otra?

Si el commit aporta trabajo relacionado, pero no cierra la tarea, usa Refs. Si el commit soluciona realmente la incidencia, usa Fixes.

8.2. Integración continua¶

Si el equipo usa una convención estable, la integración continua puede validar el formato del commit y, en algunos casos, automatizar el cálculo de versiones y la publicación de releases.

Dicho de forma sencilla: el commit deja de ser solo un texto para personas y se convierte también en una entrada útil para la automatización.

9. Breaking changes y versionado semántico¶

Un breaking change es un cambio que rompe compatibilidad con versiones anteriores. Por ejemplo:

renombrar un endpoint consumido por otros clientes;
eliminar un parámetro obligatorio;
cambiar la estructura de un dato público;
modificar el contrato de una API.

En estos casos conviene marcarlo de forma explícita:

feat(api)!: renombrar el campo id a userId

BREAKING CHANGE: el campo id deja de existir en la respuesta del endpoint /users.

Esto es importante porque conecta con Semantic Versioning:

fix suele asociarse a cambios de parche;
feat suele asociarse a cambios menores;
un BREAKING CHANGE suele implicar cambio de versión mayor.

Error frecuente

No basta con poner ! si el cambio rompe compatibilidad. También conviene explicar qué se rompe y, si es posible, cómo migrar.

10. Ejemplos buenos y malos¶

10.1. Ejemplos recomendables¶

feat(ui): añadir filtro por estado en la lista de incidencias

fix(auth): corregir la expiración del token en peticiones concurrentes

Se evita que varias renovaciones simultáneas invaliden la sesión del usuario.
Fixes: #142

docs(git): añadir plantilla de commits para el equipo

refactor(parser): extraer validación de cabeceras a una función dedicada

Se mejora la legibilidad y se reduce duplicación sin cambiar el comportamiento.

10.2. Ejemplos a evitar¶

Mensaje	Problema
`update`	No dice qué se ha hecho ni por qué.
`cambios varios`	Mezcla modificaciones y no aporta trazabilidad.
`fix`	Falta contexto y descripción.
`WIP`	Puede servir localmente, pero no debería ensuciar el historial final.
`arreglos de hoy`	Es ambiguo y no se puede reutilizar como documentación técnica.

11. Buenas prácticas para clase y para empresa¶

Estas pautas son especialmente útiles cuando el alumnado empieza a trabajar con repositorios compartidos:

Haz commits pequeños y con una sola intención.
No mezcles en el mismo commit una corrección, un refactor y cambios de formato.
Escribe el mensaje pensando en quien lo leerá después, no solo en quien lo crea ahora.
Usa cuerpo cuando el motivo del cambio no sea evidente.
Mantén una convención común en todo el proyecto.
Si trabajas en equipo, acordad tipos y scopes antes de empezar.
Revisa el commit antes de crearlo igual que revisas el código.

Plantilla mínima reutilizable

tipo(scope): resumen breve

Contexto o motivo del cambio.

Refs: #ID
Fixes: #ID
BREAKING CHANGE: impacto y migración

12. Errores frecuentes del alumnado¶

Al empezar a trabajar con Git, suelen aparecer estos problemas:

usar mensajes demasiado genéricos;
hacer un único commit después de muchas tareas distintas;
describir solo el resultado y no la intención;
no indicar cuándo un cambio rompe compatibilidad;
escribir mensajes inconsistentes dentro del mismo proyecto.

Estos errores no son raros, pero conviene corregirlos pronto porque afectan directamente a la calidad del trabajo colaborativo.

13. Conclusión¶

Un commit profesional es una herramienta de comunicación técnica. Sirve para registrar cambios, colaborar mejor y dejar un historial que realmente ayude a mantener el software.

La idea que debes recordar es esta: un buen commit no solo guarda código; también deja contexto, intención y trazabilidad. Si el historial ayuda a comprender el proyecto sin esfuerzo innecesario, entonces los commits están haciendo bien su trabajo.

6.1.1.-Commits profesionales