Buenas prácticas para crear una Pull Request

Las Pull Requests son una parte fundamental en el día a día de programadores y programadoras. Muchos días dedicamos varias horas tanto a crearlas como a revisarlas, por lo que es importante tener en cuenta varias cosas antes de hacerlo.

Crear bien una Pull Request ayudará a que nuestros compañeros tengan el contexto de qué se quiere hacer, de por qué se ha hecho y de cómo está funcionando todo.

Qué es una Pull Request

Una Pull Request permite a otras personas revisar los cambios que has hecho en una rama de un repositorio git. Una vez se abre una Pull Request, es posible debatir y ver qué cambios se han hecho en un proyecto. Se pueden añadir comentarios, sugerencias y en definitiva, que esté todo el mundo de acuerdo en que ese código debe ser aprobado o no.

Cómo crear una Pull Request

Crear una Pull Request es realmente sencillo utilizando cualquiera de los servicios en los que se pueden alojar repositorios: Github, Bitbucket, Gitlab, Azure...

El proceso es el mismo para todos ya que primero deberemos crear una rama en nuestro repositorio:

git checkout -b nombre-de-la-rama

Tras esto, haremos los cambios que correspondan, tocaremos el código del proyecto y haremos un commit:

git add .
git commit -m "feat(subscriptions): enable subscription payment"

Hablando de commits, te recomendamos que leas este artículo sobre cómo escribir buenos commits en Git.

Una vez hayamos hecho el commit, simplemente tendremos que hacer un push al origin:

git push -u origin nombre-de-la-rama

En este momento ya podremos crear una Pull Request en la plataforma en la que tengamos alojado nuestro código.

Ahora que ya sabemos qué es y cómo crear una Pull Request, vamos a hablar de las buenas prácticas que hay que seguir cuando creamos la Pull Request y asignamos revisores.

Revisa tu propia Pull Request

Antes de pedir que nos revisen una Pull Request es importante estar seguro de que está lista para ser revisada y también de que cumple con ciertos criterios:

• Tests
• Documentación
• Pre-commit para evitar comentarios sobre formateo

Revisa tus propios cambios antes de pedir que te los revisen porque puede que se te haya pasado algo y así evitas que en tu equipo pierdan el tiempo revisando cosas que tú mismo podrías ver.

Comenta tu propia Pull Request

Hay cambios que puede que tus compañeros no entiendan muy bien por qué los has hecho. Es posible que entiendan el código, pero probablemente no sean capaces de ver qué motivos hay detrás de ciertos cambios. Por eso, antes de asignar revisores dedica 5 minutos a pasar por tu código y añadir comentarios donde veas necesaria alguna explicación, por mínima que sea.

Haz Pull Requests pequeñas

Las Pull Requests grandes pueden llegar a estar varios días abiertas y esto es algo que resta mucha agilidad en un equipo. Revisar una Pull Request debería ser un proceso rápido para que ésta pueda cerrarse pronto. Muchos cambios de foco y comentarios ping-pong asíncronos no nos interesan porque harán que perdamos la concentración en las cosas que estemos trabajando.

Cuanto más pequeñas sean las Pull Requests, mejor.

Escribe una buena descripción

Escribir una buena descripción en una Pull Request es una de las partes más importantes y que más ayudarán a la hora de revisarla. Si la persona que revisa el código ve 300 líneas añadidas, 100 borradas y varios archivos renombrados, lo más probable es que no sepa el motivo de esos cambios, así que para ayudarle a revisar tu código, deja una buena descripción en la que expliques qué has hecho y por qué.

Escribir una descripción completa en una Pull Request ayudará a dar contexto en la revisión.

Automatiza todo lo posible

La recomendación de automatizar todo lo posible sirve en muchos ámbitos, y también en las Pull Requests. La automatización ayudará a eliminar ciertos procesos manuales que probablemente se nos olviden cuando vamos con prisa por completar una funcionalidad, desplegar a producción...

¿Qué se debería automatizar en una Pull Request?

• Testing: cada vez que se abre una Pull Request se deberían pasar los tests automáticamente, y también cuando se hace un nuevo commit a una Pull Request ya abierta. A menos que pasen los tests, la rama no se podrá mergear.
• Documentación: mantener la documentación es un proceso realmente tedioso, por lo que cuanto más automatizado esté el proceso, mejor. Por ejemplo, si estamos desarrollando una API que tiene documentación podríamos automatizar su generación a OpenAPI, por ejemplo.
• Formateo del código: formatear el código también puede automatizarse y bloquear un commit si el formato no es el correcto. Haz esto para evitar comentarios en tu Pull Request del estilo de "esta línea es demasiado larga", "este método es muy grande", "esta clase no tiene el nombre en el formato correcto".

Crea una plantilla para Pull Requests

Hemos hablado de que es importante añadir una descripción a la Pull Request, hablar de qué hemos hecho y por qué lo hemos hecho, puede que asignar una tarea de Jira a la rama o añadir un checklist del tipo "¿has añadido documentación?", "¿has revisado tu propio código?", "¿has escrito suficientes tests?"...

Si es algo que siempre estamos escribiendo al crear una Pull Request, lo mejor es crear una plantilla para no tener que estar siempre escribiéndolo.

Debate los cambios que harás con tus compañeros antes de implementarlos

Muchas veces (por no decir casi siempre) un problema puede solucionarse de varias maneras. A la hora de escribir código, valora cuánto esfuerzo te va a llevar antes de ponerte a programar y si ves que te va a llevar mucho tiempo habla con tus compañeros para contarles cómo habías pensado en solucionar el problema y estructurar el código para ver si ellos están de acuerdo.

Cuando la funcionalidad es pequeña y está muy acotada no es necesario debatir su solución, pero si vas a estar varios días desarrollando código mejor plantea tu solución a tus compañeros para que no te sugieran cambiar toda la funcionalidad en la Pull Request. Si haces esto, evitarás comentarios como "yo aquí habría utilizado este patrón", "el modelo de base de datos podría ser de otra manera", "esta funcionalidad podría haberse hecho en 30 líneas en lugar de 300". Los comentarios que recibirás tendrán mucho menos potencial de cambio porque ya estábais de acuerdo en cómo solucionar el problema.

Responde rápido a los comentarios

Antes hemos comentado que los cambios de contexto provocan mucha desconcentración y sobre todo cuando pasa mucho tiempo hasta que vuelves a tener un problema en la cabeza. Cuando abres una Pull Requests los revisores estarán haciendo un gran esfuerzo por meterse tu problema en la cabeza, y es menos costoso para ellos cambiar de foco varias veces en poco tiempo que en mucho tiempo.

Por ejemplo, si abres una Pull Request y te dejan comentarios, no contestes a los comentarios al día siguiente o a los dos días porque los revisores ya se habrán olvidado de ella y necesitarán un buen rato para volver a ponerse en contexto. Sin embargo, si la cerráis en 3 horas ya tendrán el problema en la cabeza y les costará menos cambiar su foco de concentración.