Pull Request | Jose Ricardo Zapata

Ultima actualización: 1/Abr/2025

Los Pull Requests (PRs) son una piedra angular en el desarrollo de software moderno y colaborativo. Permiten a los equipos revisar cambios, discutir implementaciones y mantener la calidad del código antes de que este se integre a la base principal. Pero, ¿cómo podemos asegurarnos de que nuestros PRs sean efectivos y fáciles de revisar?

¿Qué es un Pull Request?

En esencia, un Pull Request es una solicitud formal para integrar cambios de código (desde una rama secundaria o branch) en otra rama (usualmente la principal, como main o develop). Sin embargo, es mucho más que eso:

Es una oportunidad para la revisión colaborativa: Varios ojos revisan el código propuesto.
Es un mecanismo de aseguramiento de la calidad: Ayuda a detectar errores, inconsistencias o mejoras potenciales antes de la integración.
Es un foro de discusión técnica: Permite debatir sobre la implementación, la arquitectura y la eficiencia del código.
Es una herramienta de aprendizaje y mentoring: Los desarrolladores más experimentados pueden guiar a los más nuevos, y todos aprenden de las revisiones.

El propósito fundamental es tener una revisión exhaustiva que asegure que los cambios son correctos, eficientes, cumplen el objetivo de la tarea asignada y se alinean con los estándares del proyecto. Fomenta la calidad del software y conduce a un proceso de desarrollo más sólido y confiable.

El Ciclo de Vida de un Pull Request: Paso a Paso

Crear y gestionar un PR efectivo sigue un proceso estructurado:

Tarea (Issue/Ticket):
- Comprender a fondo: Antes de escribir una línea de código, lee y entiende la tarea asignada. Pregúntate: ¿Qué se necesita hacer? ¿Para qué? ¿Cómo se sugiere abordarlo?
- Responsabilidad Única: ¿La tarea tiene un alcance claro y limitado (principio de responsabilidad única)? Si es muy grande, considera dividirla.
- Planificación: Realiza un esquema mental o escrito de cómo abordarás la tarea.
Branch y Código:
- Crear Branch: Crea una nueva rama descriptiva desde la rama base actualizada (ej. feature/TICKET-123-agregar-login).
- PR en Borrador (Draft): Tan pronto crees la rama, abre un Pull Request en modo “Draft” o “Borrador” en tu plataforma (GitHub, GitLab, Bitbucket). Copia la información relevante del issue/tarea en la descripción. Esto comunica al equipo en qué estás trabajando.
- Desarrollo: Escribe el código necesario para completar la tarea.
- Pruebas Unitarias: Implementa pruebas unitarias que validen tus cambios.
Revisión Propia y Preparación:
- Calidad del Código: Revisa tu propio código. ¿Sigue las guías de estilo del proyecto? ¿Es legible? ¿Hay código comentado innecesario?
- Pruebas Unitarias: Asegúrate de que todas las pruebas unitarias pasen localmente.
- Push: Sube tus cambios a la rama remota (git push).
- Verificar CI/CD: Revisa si los pipelines de Integración Continua (CI) se ejecutan correctamente (build, tests automatizados, linters).
- Revisar Bots: Atiende cualquier comentario o sugerencia de bots automáticos (calidad de código, seguridad, etc.).
PR Activo y Comentarios:
- Completar Descripción: Asegúrate de que la descripción del PR (ver sección siguiente) esté completa y sea clara.
- Asignar Revisores: Selecciona a los miembros del equipo adecuados para revisar tu PR (generalmente 2 o más, según las políticas del equipo).
- Activar el PR: Cambia el estado de “Draft” a “Ready for Review” (o similar).
- Comunicar: Notifica a los revisores (a través de la plataforma o un mensaje directo si es necesario).
- Atender Comentarios: Mantente atento a los comentarios de los revisores. Responde a sus preguntas, discute las sugerencias y realiza los cambios necesarios (haciendo push a la misma rama).
Aprobación e Integración (Merge):
- Aprobaciones: Consigue el número mínimo de aprobaciones requeridas por el equipo.
- Squash and Merge (Opcional pero Recomendado): Considera usar “Squash and Merge”. Esto combina todos los commits de tu rama en uno solo antes de fusionar, manteniendo el historial de la rama principal más limpio. El mensaje de commit debe ser descriptivo.
- Eliminar Rama: Una vez fusionado, elimina la rama de feature.
- Actualizar Proyecto Local: Actualiza tu copia local de la rama principal (git checkout main; git pull).
- Comunicar (Opcional): Menciona brevemente en la reunión diaria (daily) que la tarea se ha completado e integrado.

Anatomía de un Pull Request Ejemplar

¿Qué hace que un PR sea realmente bueno, de esos que los revisores agradecen? Se reduce a unos pocos elementos clave bien ejecutados.

1. El Tamaño Importa (¡Y Mucho!)

Cuanto más pequeño, mejor. Un PR conciso y enfocado trae múltiples beneficios:

✅ Revisión más rápida: Menos código significa menos tiempo para entender y evaluar.
✅ Revisión más profunda: Los revisores pueden centrarse en los detalles sin sentirse abrumados.
✅ Menos probabilidad de introducir bugs: Es más fácil razonar sobre cambios pequeños.
✅ Menos pérdida de tiempo si es rechazado: Si algo fundamental está mal, se pierde menos esfuerzo.
✅ Fácil de mezclar (merge): Menos probabilidad de conflictos con otros cambios.
✅ Menos bloqueos: Los PRs pequeños no bloquean a los revisores por largos periodos.
✅ Más simple de revertir (rollback): Si algo sale mal después del merge, es más fácil deshacer un cambio pequeño y atómico.

“Un Pull Request pequeño tiene mucha más facilidad de que sea aceptado. Lo primero que hago cuando recibo una notificación acerca de un Pull Request es revisarlo para tener una idea acerca de su tamaño. Se necesita tiempo para revisar adecuadamente uno, y en mi experiencia, el tiempo que tarda es exponencial con el tamaño; la relación ciertamente no es lineal.”

¿Cómo lograr PRs pequeños?

💡 Atomizar: Divide las tareas, features o issues grandes en subtareas más pequeñas y manejables. Cada subtarea puede ser un PR.
💡 Dividir por capas o archivos: Si una tarea afecta múltiples partes (data engineering, data science,machine learning, despliegue), considera PRs separados si es lógico y no rompe la funcionalidad intermedia.
💡 Separar refactorizaciones: Si necesitas refactorizar código existente para implementar una nueva feature, hazlo en un PR separado antes de empezar la feature. No mezcles refactorización masiva con lógica nueva.

¿Cuál es el tamaño adecuado? Depende del contexto, pero como regla general, menos de diez archivos modificados y unos pocos cientos de líneas de código cambiadas suele ser manejable. Si tu PR es mucho más grande, pregúntate si se puede dividir.

Perspectiva Ágil: Los PRs pequeños encajan perfectamente con la filosofía ágil: entregas incrementales, feedback rápido y adaptación continua. Aunque puede haber un pequeño overhead en crear más issues y PRs, los beneficios en velocidad de revisión, menor riesgo y flujo constante suelen compensarlo. La clave es una buena planificación inicial para modularizar el trabajo.

2. Una Descripción Clara y Concisa

La descripción del PR es tu oportunidad de guiar al revisor. No asumas que conocen todo el contexto. Una buena descripción:

✅ Proporciona Contexto: Explica por qué este cambio es necesario (enlaza al issue/tarea).
✅ Previene Código Innecesario: Al explicar el qué y el por qué, los revisores pueden identificar si el enfoque es correcto o si hay una solución más simple.
✅ Conduce a Mejores Soluciones: La claridad invita a discusiones constructivas sobre el enfoque.
✅ Facilita la Revisión: Un revisor informado es un revisor eficiente.
✅ Sirve como Documentación: Es una fuente de conocimiento sobre la evolución del código base.

¿Cómo lograr una buena descripción? Incluye:

💡 Descripción breve de la tarea: ¿Qué problema resuelve o qué feature implementa?
💡 Qué cambios se introducen: Un resumen de alto nivel de la solución implementada.
💡 Por qué se hicieron los cambios de esta manera: Justifica decisiones clave de diseño o arquitectura si no son obvias.
💡 Cómo probar los cambios: Instrucciones claras para que el revisor pueda verificar la funcionalidad (manual o automáticamente).
💡 Screenshots/GIFs (si aplica): Especialmente útil para cambios en la interfaz de usuario.
💡 Links a otros PRs o Issues: Si hay dependencias o trabajo relacionado.

Considera usar plantillas de PR (PULL_REQUEST_TEMPLATE.md) en tu repositorio para estandarizar las descripciones.

3. El Arte de la Revisión (Review)

La revisión de código es una calle de doble sentido. Es tanto una herramienta para mantener y mejorar la calidad del código como una oportunidad invaluable de mentoring y aprendizaje compartido.

Para el AUTOR del PR:

El trabajo no termina al abrir el PR. Mantente disponible para responder preguntas y realizar ajustes.
No tomes los comentarios como algo personal. El objetivo es mejorar el producto, no criticarte a ti.
Sé amable y agradece el tiempo de los revisores.
Si no entiendes un comentario, pide aclaraciones.

Para el REVISOR del PR:

Lee la descripción del PR y el contexto de la tarea antes de sumergirte en el código.
No asumas intenciones; si algo no está claro, pregunta.
Piensa colaborativamente. El objetivo es construir juntos.
Sé amable y constructivo. En lugar de decir “Esto está mal”, explica por qué crees que podría mejorarse y, si es posible, sugiere una alternativa ("¿Qué tal si intentamos…?" o “Considera este enfoque…”).
Enfócate en el “por qué” detrás de tus comentarios, no solo en el “qué”.

Checklist para Revisores:

💡 Propósito: ¿Los cambios concuerdan con el propósito del PR y la tarea asociada? ¿Hace lo que dice que hace?
💡 Alcance: Revisa los archivos cambiados. ¿Son los esperados? ¿Hay cambios inesperados o fuera de alcance?
💡 Claridad y Diseño: ¿El código es claro, legible y sigue las convenciones del proyecto? ¿Está bien diseñado o es innecesariamente complejo? ¿Los nombres (variables, funciones, clases) son descriptivos?
💡 Comentarios: ¿Hay comentarios claros y útiles donde son necesarios? ¿Explican el por qué de algo no obvio, más que el qué hace el código?
💡 Pruebas: ¿El código tiene pruebas unitarias (o de otro tipo según corresponda)? ¿Las pruebas son significativas, cubren los casos importantes (incluyendo bordes y errores) y están bien diseñadas?
💡 Funcionalidad: ¿Funciona correctamente? (Si es posible probarlo).
💡 Seguridad y Rendimiento: ¿Introduce alguna vulnerabilidad obvia o problema de rendimiento?

Consejos Adicionales (Sugerencias)

No expliques lo obvio, pero ten cuidado: Lo que es obvio para ti hoy puede no serlo para otro miembro del equipo, o incluso para ti mismo dentro de unos meses. Usa tu juicio.
Functional Walkthrough para PRs Grandes: Si un PR es inevitablemente grande o complejo, considera una breve sesión (5-15 min) donde el autor explica la tarea y el código a los revisores. Esto puede agilizar la revisión y resolver dudas rápidamente.
- 5-8 minutos: Explicación general de la tarea y el enfoque del código.
- Max 10 minutos: Preguntas y respuestas.
Discusiones Largas -> Reunión: Si surgen muchas diferencias o comentarios extensos que requieren un debate profundo, es más eficiente tener una reunión corta que llenar el PR con decenas de comentarios de ida y vuelta.

Conclusión

Adoptar buenas prácticas en los Pull Requests transforma un proceso potencialmente tedioso en una poderosa herramienta de colaboración y mejora continua. Al enfocarnos en PRs pequeños y bien definidos, con descripciones claras y fomentando revisiones constructivas y amables, no solo mejoramos la calidad de nuestro código, sino que también fortalecemos la comunicación y el aprendizaje dentro del equipo.

Referencias

Jose R. Zapata