Como mantenedor, revisar pull requests es algo que harás con bastante regularidad.
Este documento contiene algunas pautas de revisión de pull requests específicas de Exercism.
Revisar pull requests de ejercicios
Revisar un pull request de un Concept Exercise o un Practice Exercise puede ser abrumador, con tantas reglas en torno a este tipo de ejercicio.
Por eso, una primera revisión hecha por un mantenedor suele llevar de dos a tres horas y da como resultado decenas de comentarios.
En los Concept Exercises también hay archivos con objetivos o contenidos similares (por ejemplo, la introducción del ejercicio y la del concepto), así que es fundamental centrarse primero en dejar uno de ellos perfecto antes de extenderse demasiado en otras direcciones.
Para ayudar a agilizar este flujo de trabajo, hemos desarrollado las siguientes recomendaciones.
Recomendación: que un mantenedor sénior se encargue de la primera revisión
Las razones para que exactamente un 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 conjunto en el pull request, lo que, con suerte, le dará al colaborador la sensación de que no está haciendo esto solo
- No habrá comentarios de revisión contradictorios de otros mantenedores
Recomendación: fusionar con el estado wip
Una vez que el colaborador y el mantenedor estén conformes con el ejercicio, este debe fusionarse con su status en wip (trabajo en curso).
Los ejercicios con este estado no estarán disponibles para los estudiantes, pero sí podrán verlos nuestros mejores mentores (cuando implementemos esto en algún momento del futuro).
Estos usuarios con alta reputación podrán entonces probar el ejercicio y crear issues o pull requests para corregirlo o mejorarlo.
Los principales beneficios de este enfoque son:
- Elimina la carga sobre el par original de colaborador y mantenedor de tener que dejarlo todo perfecto
- No genera ciclos enormes de pull requests con múltiples voces (que son muy difíciles de gestionar)
Revisar pull requests de Practice Exercises
Recomendación: plantearse si el cambio pertenece en realidad a problems-specifications
Parte del contenido de un Practice Exercise (como su introducción) proviene de sus metadatos (compartidos) tal como se definen en el repositorio problems-specifications.
Cuando revises un pull request que cambie ese contenido, plantéate si el cambio también podría beneficiar a otros tracks.
Si es así, sugiere al colaborador que abra un pull request al archivo correspondiente en el repositorio problems-specifications.
Recomendaciones generales de revisión
Recomendación: un revisor principal por pull request
Todos los pull requests deben tener un revisor principal (el mantenedor que lo asuma).
Otros mantenedores o miembros de la comunidad deben actuar en un rol secundario.
Hay dos formas principales en que alguien con un rol secundario puede contribuir a una revisión:
- Revisar la ortografía y la gramática, pero solo una vez que haya ocurrido la primera revisión del revisor principal.
Puede ser frustrante para los colaboradores recibir una revisión de ortografía y gramática, corregirla, y luego que llegue un mantenedor y les pida cambios de fondo.
En otras palabras: la revisión de ortografía y gramática es algo que haces después de que se resuelvan los cambios de fondo (o quizás en un pull request de seguimiento).
- Señalar cosas al revisor sin plantearlas como algo que deba hacer.
Si comentas cosas que el revisor principal debería considerar o que quizás se le pasaron, publica tu comentario como una opinión o formulado como una pregunta.
Esto deja claro al colaborador que no le estás pidiendo que haga cambios, lo que le resultará menos confuso.
También reducirá la probabilidad de que el revisor principal se sienta «desautorizado».
Recomendación: no comentes cosas que no vengan al caso
Cuando revises un pull request, comenta solo sobre 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
Cuando sea posible, intenta siempre enlazar a documentación que explique por qué estás comentando algo.
Esto ayuda mucho a reducir la probabilidad de que la conversación se vuelva conflictiva.
Recomendación: pide ayuda a otros equipos
Si quieres pedir ayuda para revisar un pull request, tenemos dos equipos específicos a los que puedes avisar:
-
@exercism/reviewers: para cualquier revisión general
-
@exercism/github-actions: para cualquier duda sobre GitHub Actions
