Quand on est mainteneur, relire des pull requests fait partie des choses que l'on fait assez régulièrement. Ce document rassemble quelques recommandations propres à Exercism pour la revue des pull requests.
Relis les pull requests d'exercices
Relire une pull request pour un exercice d'apprentissage ou un exercice d'entraînement peut sembler intimidant, vu le nombre de règles qui encadrent ce type d'exercice. C'est pourquoi une première revue par un mainteneur prend souvent deux à trois heures et donne lieu à des dizaines de commentaires. Pour les exercices d'apprentissage, certains fichiers poursuivent aussi des objectifs et ont des contenus similaires (par exemple l'introduction de l'exercice et celle du concept) : il est alors essentiel de se concentrer d'abord sur l'un d'eux pour le rendre parfait avant de s'éparpiller trop loin.
Pour rendre ce workflow plus fluide, voici les recommandations que nous avons mises au point.
Recommandation : confie la première revue à un seul mainteneur expérimenté
Voici pourquoi il vaut mieux confier la première revue à un seul mainteneur expérimenté :
- Le travail de relecture n'est pas fait en double.
- Le contributeur et le mainteneur travaillent en binôme sur la pull request, ce qui, on l'espère, donne au contributeur le sentiment de ne pas être seul.
- Il n'y a pas de commentaires de revue contradictoires venant d'autres mainteneurs.
Recommandation : fusionne en statut wip
Une fois que le contributeur et le mainteneur sont tous les deux satisfaits de l'exercice, celui-ci peut être fusionné avec son status défini sur wip (travail en cours). Les exercices qui portent ce statut ne seront pas accessibles aux apprenants, mais ils pourront être consultés par nos mentors les plus expérimentés (une fois que nous aurons mis cela en place, à l'avenir). Ces utilisateurs à la réputation élevée pourront alors tester l'exercice et créer des issues ou des pull requests pour le corriger ou l'améliorer.
Les principaux avantages de cette approche sont les suivants :
- Elle enlève au binôme contributeur/mainteneur d'origine la charge de tout rendre parfait.
- Elle évite les cycles interminables de pull requests où plusieurs personnes donnent leur avis, et qui sont vraiment difficiles à gérer.
Relis les pull requests d'exercices d'entraînement
Recommandation : vérifie si la modification a vraiment sa place dans problems-specifications
Une partie du contenu d'un exercice d'entraînement (comme son introduction) provient de ses métadonnées (partagées) telles que définies dans le dépôt problems-specifications. Quand tu relis une pull request qui modifie ce genre de contenu, demande-toi si la modification pourrait aussi profiter à d'autres parcours. Si c'est le cas, suggère au contributeur d'ouvrir une pull request sur le fichier correspondant dans le dépôt problems-specifications.
Recommandations générales de revue
Recommandation : un relecteur principal par pull request
Chaque pull request devrait avoir un relecteur principal, quel que soit le mainteneur qui s'en charge. Les autres mainteneurs et/ou membres de la communauté interviennent dans un rôle secondaire.
Il y a deux grandes façons, pour une personne dans un rôle secondaire, de contribuer à une revue :
- Relire l'orthographe et la grammaire, mais seulement une fois que le relecteur principal a fait sa première passe. C'est frustrant pour un contributeur de recevoir une relecture d'orthographe et de grammaire, de la corriger, puis de voir un mainteneur débarquer et lui demander des changements plus fondamentaux. Autrement dit, la relecture de l'orthographe se fait après avoir réglé les changements fondamentaux (ou éventuellement dans une pull request de suivi).
- Signaler des points au relecteur sans lui demander d'agir. Si tu commentes des choses auxquelles le relecteur principal devrait réfléchir ou qu'il a peut-être manquées, formule ton commentaire comme un avis ou une question. Ainsi, le contributeur comprend clairement que tu ne lui demandes pas de modifier quoi que ce soit, ce qui rend les choses moins confuses pour lui. Cela réduit aussi le risque que le relecteur principal se sente « décrédibilisé ».
Quand tu relis une pull request, ne commente que ce qui s'y rapporte directement. Pour tout le reste, ouvre une issue ou crée une pull request séparée (de suivi).
Recommandation : mets un lien vers la documentation
Dans la mesure du possible, essaie toujours de renvoyer vers une documentation qui explique pourquoi tu commentes quelque chose. Cela réduit grandement le risque que la discussion tourne à la dispute.
Recommandation : demande de l'aide aux autres équipes
Si tu veux de l'aide pour relire une pull request, tu peux interpeller deux équipes spécifiques :
-
@exercism/reviewers : pour toute revue générale
-
@exercism/github-actions : pour toute question concernant les GitHub Actions
