Muchos son los errores que la mayoría de la gente comete al crear una Pull Request. Estos errores favorecen a que la Pull Request sea difícil de revisar por tus compañeros y que, por tanto, les tome más tiempo y energía.
Para explicar los errores más comunes, hemos de entender cuál es la esencia de las Pull Request.
Que es una pull request?
Podríamos definir de manera pragmática que una Pull Request es una proposición de valor a nuestro repositorio del código que o bien aporta valor al desarrollador mejorando la experiencia de desarrollo de alguna manera, o que, por otro lado, aporta valor al usuario con un incremento de producto en forma de nueva funcionalidad o solventando un bug que existe en la aplicación.
Es conveniente que el tiempo de vida de las Pull Request sea lo más corto posible. Es decir, que el tiempo entre que se crea la Pull Request y que se ha aprobado y mergeado sea el mínimo, porque eso significa que hemos entregado valor lo más rápido posible.
Pilares fundamentales para crear una Pull Request exitosa
Para asegurarte de que tus Pull Request son exitosas y que se aprueban rápidamente, te recomiendo tener en mente "los tres pilares fundamentales".
- La Pull Request ha de ser fácil de revisar
- La Pull Request ha de ser rápida de revisar
- La Pull Request ha de ser una unidad
Teniendo en cuenta estos tres pilares fundamentales, te voy a listar a continuación algunos de los errores que se cometen más a menudo y que impiden que una Pull Request sea ágil de ser revisada.
Errores que debes evitar al crear una Pull Request
1. No añadir cuál es el objetivo de la Pull Request
Esto viola los siguientes pilares fundamentales: “La PR ha de ser fácil de revisar” y “La PR ha de ser rápida de revisar”.
Toda Pull Request trata o bien de solucionar un problema o aportar una mejora. Este objetivo ha de estar plasmado en la descripción.
Al ocultar cuál es el objetivo de la Pull Request estamos forzando a que el revisor no se plantee ciertas preguntas.
- ¿Tiene sentido este incremento de producto?
- ¿Es necesario?
- ¿Qué cosas tengo que tener en cuenta?
Y no solo eso, sino que estamos forzando a que el revisor adopte el rol de "linter" así fijándose mayormente en si hay errores de escritura, typos, etc. (Ya hablaremos en otro artículo de los distintos roles que podemos adoptar al revisar una Pull Request.)
2. No añadir las especificaciones de la tarea ni la bibliografía relacionada
Esto viola el pilar fundamental: “La PR ha de ser fácil de revisar”
Partimos de la idea de que todo trabajo que realizamos tiene que tener una especificación que ha sido definida directa o indirectamente.
La especificación de la tarea es el conjunto de indicaciones y requerimientos que nuestra funcionalidad ha de cumplir.
La persona que revisa la Pull Request tiene que tener claras esas especificaciones para poder evaluar si el código se comporta como debería.
Por ejemplo, si estamos construyendo un componente visual para representar un producto cualquiera de nuestra tienda online, las especificaciones deberían plasmar los distintos componentes visuales que esta debería tener.
- Como se ha de mostrar el título
- Como se ha de mostrar la descripción
- Como se ha de mostrar el precio
Si las especificaciones de la tarea no están indicadas en ningún lugar, la persona que revisa la Pull Request no tendrá la información necesaria para revisarla de manera significativa.
Como podría saber la persona que revisa la Pull Request que por ejemplo el componente "ProductCard" ha de incluir las tallas del producto si no tenemos las especificaciones indicadas en ningún lugar. En este caso, es probable que el revisor apruebe la Pull Request porque el código se ve bien, pero realmente no sería correcto, pues la Pull Request no cumplía con las especificaciones establecidas porque la "ProductCard" no muestra las tallas de la ropa.
3. No añadir como se ha de probar el código
Esto viola el pilar fundamental: “La PR ha de ser fácil de revisar”
Para aprobar una Pull Request hemos de verificar que el código cumple unas especificaciones concretas. Para ello, hemos de poder recrear el escenario para verificar dichas especificaciones.
En el ejemplo mencionado anteriormente de la "ProductCard", el usuario que revisa la Pull Request tiene que tener claro que información ha de mostrar el nuevo componente "ProductCard" y verificar que la muestra.
Si por ejemplo estamos solucionando un error que sucede cuando un usuario invitado aplica un código promocional en el carrito de la compra, tendremos que indicar los distintos pasos para replicar este escenario.
- ¿Cómo recreo ese rol para ese usuario?
- ¿Qué tipo de producto o productos tengo que añadir al carrito?
- ¿Tengo que probar un código promocional en concreto o puede ser cualquiera?
4. Añadir cambios al código que no se relacionan con el objetivo de la Pull Request
Esto viola los siguientes pilares fundamentales: “La PR ha de ser una unidad” y “La PR ha de ser rápida de revisar”.
Siempre se ha dicho que una de las mejores prácticas que podemos tener como ingeniero de software es la de dejar el código mejor de lo que nos lo hemos encontrado. A esta práctica se la conoce como la regla del boy scout. ¿Pero hasta qué punto esto es bueno?
Solo deberíamos modificar código que está directamente relacionado con el objetivo de la Pull Request.
Podemos hacer todo tipo de refactors. Cambios de nombre, extraer lógica en métodos, crear sub-componentes, nuevos servicios, etc. Pero siempre evitando grandes refactors. En caso de querer hacer un refactor grande, es mejor separarlo en otra tarea y Pull Request. En caso de no hacerlo, estamos incrementando el tamaño de la Pull Request y su complejidad accidental.
5. Hacer Pull Requests que sean muy largas
Esto viola el pilar: “La PR ha de ser rapida de revisar”
Está comprobado que cuanto más larga es la Pull Request, más tiempo pasa hasta que alguien la revise.
Esto se puede solucionar acotando las tareas e intentando que sean lo más granulares posibles además de evitar el error mencionado anteriormente (4).
Imagínate el escenario de qué producto quiere añadir las tallas de los productos en nuestro componente "CardProduct". Si para conseguir dicho comportamiento tenemos que refactorizar el componente "Tag", este desarrollo debería tener su propia tarea y también su propia Pull Request.
Gracias a tener tareas y Pull Requests separadas para estos dos desarrollos, ganaremos cohesión en nuestros incrementos de producto, así como también reduciremos el tamaño y la complejidad de las Pull Requests.
6. Mantener conversaciones relacionadas con un comentario de la Pull Request en otros canales
Esto viola los siguientes pilares fundamentales: “La PR ha de ser una unidad” y “La PR ha de ser rápida de revisar”.
Es importante que todas las conversaciones relacionadas con la Pull Request se puedan encontrar en esta misma. Esto servirá como documentación y enriquecerá el contexto de la Pull Request para otros revisores, tanto en ese momento, como en el futuro.
Algunas veces es mejor tener una conversación vía llamada o mensaje directo en caso de haber un gran número de preguntas o que las respuestas sean muy complejas y/o largas. Esto no significa que nos debamos quedar aquí, sino que deberíamos actualizar la Pull Request con un resumen las conclusiones que surgido de dicha conversación.
