La description de Pull Request parfaite

Quand on développe en équipe, la politesse des personnes se reflète dans le code :

  • les idiomes de la base de code sont-ils respectés ?
  • le style des messages de commit est-il respecté ?
  • le ton des commentaires est-il professionnel ?
  • une relecture a-t-elle été effectuée avant de solliciter une revue ?
  • etc.

Or, dans la vraie vie, tout le monde n'est pas toujours très poli, lol.

Pour éviter un maximum le foutoir, on met en place des guides de style, des règles, des formateurs de code automatiques etc.

Cependant, un point est souvent négligé : une description standardisée et utile de Pull Request (PR) ou Merge Request.

QQOQCCP

Pour faire une bonne description, on peut utiliser comme base le questionnement Quintilien (QQOQCCP) ou les Five W's en anglais.

La technique du "Qui ? Quoi ? Où ? Quand ? Comment ? Combien ? Pourquoi ?" permet de poser les questions indispensables à la bonne délimitation d'un sujet.

Si dans le cadre d'une PR certaines réponses sont évidentes, d'autres le sont moins :

  • "Quoi ?"
  • "Pourquoi ?"
  • "Comment ?"

En y répondant dans une description de PR, non seulement on facilite le travail de revue de code, mais en outre on réfléchit à ce qu'on fait et à pourquoi on le fait.

Ça permet au besoin de pouvoir challenger le métier, et ce même pendant la phase de développement.

Le "Pourquoi ?" et le "Comment ?" peuvent de surcroît être une aide à l'élaboration de commentaires de code pertinents.

Exemple de modèle de PR

Voici un exemple mis en place sur mon dernier projet :

### Quoi ?

Résumé des changements apportés.

## Pourquoi ?

Indiquer le problème que nous sommes en train
de résoudre et l'objectif (métier ou technique)
visé par ces changements.

### Comment ?

Attirer l'attention sur les décisions
d'architecture ou de conception importantes.

### Captures d'écran

Utile pour les changements liés à l'UI.

### Autre

- si des tests manquent, indiquer la raison,
    la probabilité, et les risques associés
    à ce manque
- être explicite sur le délai attendu pour
    une revue de code
- être explicite sur la qualité attendue
    pour la revue de code
- etc.

Vous pouvez mettre en place ce genre de modèle avec un pull request template ou un merge request template.

Pour aller plus loin

Ce billet ne concerne que la description, il y a bien d'autres aspects à prendre en compte dans le contenu d'une bonne PR.

Avant Configurer un Mac "comme j'aime" Après Les cinq règles d'or du JavaScript moderne

Tag Kemar Joint