Como mantenedor, revisar pull requests es algo que harás con bastante frecuencia.
Este documento contiene algunas pautas de revisión de pull requests específicas de Exercism.
Revisar pull requests de ejercicios
Revisar el pull request de un ejercicio de concepto o de un ejercicio de práctica puede ser abrumador dadas las numerosas reglas que rodean a este tipo de ejercicios.
Por este motivo, una primera revisión por parte de un mantenedor suele llevar de dos a tres horas y da lugar a decenas de comentarios.
En los ejercicios de concepto también hay ficheros con objetivos y contenidos similares (por ejemplo, la introducción del ejercicio y la del concepto), y centrarse primero en dejar uno de ellos perfecto es esencial antes de extenderse demasiado.
Para ayudar a agilizar este flujo de trabajo, hemos elaborado las siguientes recomendaciones.
Recomendación: que un único mantenedor sénior se encargue de la primera revisión
Los motivos para que un único mantenedor sénior se encargue de la primera revisión son:
- No se duplica el trabajo de revisión
- El colaborador y el mantenedor trabajarán en pareja en el pull request, lo que, con suerte, dará al colaborador la sensación de que no está solo en esto
- No habrá comentarios de revisión contradictorios por parte de otros mantenedores
Recomendación: fusionar con el estado wip
Cuando el colaborador y el mantenedor estén satisfechos con el ejercicio, este debería fusionarse con su status establecido en wip (work in progress, en curso).
Los ejercicios con este estado no estarán disponibles para los estudiantes, pero los mejores mentores podrán verlos (cuando lo implementemos en el futuro).
Estos usuarios con alta reputación podrán entonces probar el ejercicio y crear issues o pull requests para corregirlo o mejorarlo.
Las principales ventajas de este enfoque son:
- Elimina la carga que supone para la pareja original de colaborador y mantenedor tener que dejarlo todo perfecto
- No da lugar a ciclos enormes de pull requests con muchas voces (que son realmente difíciles de gestionar)
Revisar pull requests de ejercicios de práctica
Recomendación: plantéate si el cambio pertenece realmente a problems-specifications
Parte del contenido de un ejercicio de práctica (como su introducción) procede de sus metadatos (compartidos) tal como se definen en el repositorio problems-specifications.
Al revisar un pull request que cambie ese contenido, plantéate si el cambio podría beneficiar también a otros tracks.
Si es así, sugiere al colaborador que abra un pull request al fichero correspondiente del repositorio problems-specifications
Recomendaciones generales de revisión
Recomendación: un revisor principal por pull request
Todos los pull requests deberían tener un revisor principal (el mantenedor que se encargue de él).
Los demás mantenedores o miembros de la comunidad deberían actuar en un papel secundario.
Hay dos formas principales en las que alguien con un papel secundario puede contribuir a una revisión:
- Corregir la ortografía y la gramática, pero solo una vez realizada la primera revisión del revisor principal.
Puede resultar frustrante para los colaboradores recibir una revisión de ortografía y gramática, corregirla y que después llegue un mantenedor y les pida cambios más de fondo.
En otras palabras: la corrección ortográfica y gramatical es algo que haces después de resolver los cambios de fondo (o, quizá, en un pull request de seguimiento).
- Señalar cosas al revisor de una forma que no exija una acción por su parte.
Si comentas cosas que el revisor principal debería tener en cuenta o que quizá se le hayan pasado por alto, publica tu comentario como una opinión o formúlalo como una pregunta.
Así queda claro para el colaborador que no le estás pidiendo cambios, lo que hará que se líe menos.
También reducirá la probabilidad de que el revisor principal se sienta «desautorizado».
Recomendación: no comentes cosas que no vengan al caso
Al revisar un pull request, comenta solo las cosas directamente relacionadas con el pull request.
Para cualquier otra cosa, abre un issue o crea un pull request aparte (de seguimiento).
Recomendación: enlaza a la documentación
Siempre que sea posible, intenta enlazar a documentación que explique el motivo por el que comentas algo.
Esto ayuda mucho a reducir la probabilidad de que las cosas se conviertan en una discusión.
Recomendación: pide ayuda a otros equipos
Si quieres pedir ayuda para revisar un pull request, hay dos equipos concretos a los que puedes mencionar:
-
@exercism/reviewers: para cualquier revisión general
-
@exercism/github-actions: para cualquier duda sobre GitHub Actions
