Partagez vos changements

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 souci 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) :

• Ajoutez des commits de fixup, amend, squash ou reword à l’aide de la documentation dédiée à git commit.
• Fusionnez automatiquement les corrections dans les commits originaux de votre PR et vérifier le résultat , à l’aide de git rebase -i --autosquash origin/dev (juste avant le merge et une fois les relectures terminées).
• Poussez vos changements avec git push --force-with-lease car vous ne poussez pas seulement de nouveaux commits, mais bien un changement des commits existants.

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

Cycle de review

Une revue de code est un processus itératif. Pour la fluidité d’une review, il est impératif de configurer correctement ses notifications github.

Il est conseillé de configurer les dépôts OSRD en “Participating and @mentions”. Cela permet d’être notifié d’activités uniquement sur les issues et PR auxquelles vous participez.

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/demande de changement
    A-->>R: Corrige le code si nécessaire dans des « fixups » dédiés
    R-->>A: Vérifie, teste, et commente à nouveau le code
    R-->>A: Résout les conversations/demandes de changement 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

Les mainteneurs sont automatiquement notifiés par le système de CODEOWNERS. L’auteur d’une PR est responsable de faire avancer sa PR dans le processus de review (quitte à notifier manuellement un mainteneur).

Continuer enfin vers les tests ‣