Partagez vos changements

Comment soumettre votre code pour qu’il soit vérifié ?

L’auteur d’une pull request (PR) est responsable de son « cycle de vie ». Il se charge de contacter les différents acteurs, de suivre la revue de code, répondre aux commentaires et corriger le code suite à la revue de code (vous pouvez également consulter la page dédiée à la revue de code).

En cas de PR conséquente, ne pas hésiter à solliciter plusieurs reviewers qui pourront s’organiser, voire de faire la review ensemble, reviewers et auteur.

  1. Ouvrez une pull request
    Une fois que vos changements sont prêts, il est temps de proposer de les intégrer à la branche dev. Cela se fait dans l’interface web de Github.

    Si possible :

    • Faites des PRs d’unités logiques et atomiques également (évitez de mélanger le refactoring, les nouvelles fonctionnalités et la correction de bugs en même temps).
    • Ajoutez une description aux PR pour expliquer ce qu’elles font et pourquoi.
    • Aidez le relecteur en suivant les conseils donnés dans l’article de mtlynch.
    • Ajoutez les balises area:<affected_area> pour montrer quelle partie de l’application a été impactée. Cela peut être fait via l’interface web.
  2. Prenez en compte les retours
    Une fois que votre PR est ouverte, d’autres contributeurs doivent donner leur avis sur votre proposition :

    • N’importe qui peut donner son avis.
    • Il est nécessaire d’obtenir l’approbation d’un contributeur familier avec le code.
    • Il est d’usage de prendre en compte tous les commentaires critiques.
    • Les commentaires sont souvent écrits dans un style plutôt direct, dans le soucis de collaborer efficacement vers une solution acceptable par tous.
    • Une fois que tous les commentaires ont été pris en compte, un mainteneur intègre le changement.

Sur les PR conséquentes et vouées à évoluer dans le temps, conserver les corrections suite à la relecture dans des commits séparés facilite le travail de relecture. En cas de rebase et de relectures multiples par la même personne ils sont le moyen d’économiser une nouvelle relecture complète (demandez de l’aide au besoin) :

  1. N’hésitez pas à relancer vos interlocuteurs, plusieurs fois si besoin : vous êtes responsable de la vie de votre pull request.

Proposition de fonctionnement

Voici une proposition de flux de travail.

Il est nécessaire de communiquer par messagerie instantanée (Matrix, Slack, etc.) afin de garantir le fonctionnement du flux de la validation d’une PR.

sequenceDiagram
  actor A as Auteur PR
  actor R as Reviewer/mainteneur
  
  A->>R: Demande une review en notifiant spéciquement quelques personnes
  R->>A: Répond à la demande par oui ou non
  
  loop Boucle entre auteur et reviewer
    R-->>A: Commente, demande des changements
    A-->>R: Répond à chaque commentaire/requested changes
    A-->>R: Corrige le code si nécessaire dans des « fixups » dédiés
    R-->>A: Vérifie et commente à nouveau le code
    R-->>A: Résoud les conversations/requested changes le cas échéant
  end
 
  A->>R: Rebase si nécessaire
  R->>A: Vérifie l'historique des commits
  R->>A: Approuve ou ferme la PR
  Note left of R: Et fusionne si mainteneur

Continuer enfin vers les tests ‣