Que fait Expliquer cette PR ?
Lit une Pull Request GitHub, comprend ce qu'elle modifie et écrit une explication en français simple. La poste en commentaire sur la PR pour que les réviseurs aient un contexte immédiat.
Étape 1 : Vérifier la configuration
Confirmer que gh est authentifié :
gh auth status
Si ce n'est pas le cas : gh auth login et suivre les instructions.
Confirmer l'entrée. L'utilisateur doit fournir :
- Une URL de PR GitHub (ex.
https://github.com/proprietaire/repo/pull/123) - Un numéro de PR dans le dépôt courant (ex.
#123) - Le mot-clé "current" pour utiliser la PR de la branche active
Si aucune entrée n'est fournie, demander : "Quelle PR dois-je expliquer ? Partagez l'URL, le numéro de PR ou dites 'current' pour la branche active."
Étape 2 : Récupérer le contexte de la PR
Obtenir les métadonnées de la PR :
gh pr view URL_OU_NUMERO_DE_PR --json number,url,title,body,author,baseRefName,headRefName,additions,deletions,changedFiles,commits,labels,state,isDraft
Si isDraft est true, le signaler à l'utilisateur : "Cette PR est encore en brouillon. L'explication est basée sur son état actuel."
Obtenir le diff :
gh pr diff URL_OU_NUMERO_DE_PR
Si le diff dépasse 400 lignes, lire le résumé --stat et les 200 premières lignes du diff :
gh pr view URL_OU_NUMERO_DE_PR --json files
gh pr diff URL_OU_NUMERO_DE_PR | head -200
Obtenir les commentaires existants (pour éviter de répéter ce qui est déjà dit) :
gh pr view URL_OU_NUMERO_DE_PR --json comments --jq '.comments[].body' 2>/dev/null | head -20
Étape 3 : Rédiger l'explication
Rédiger deux paragraphes. Lire chaque règle avant d'écrire.
Paragraphe 1 : Ce que ça fait (technique)
- Une phrase par changement majeur
- Nommer les fichiers, fonctions ou systèmes spécifiques modifiés
- Indiquer l'avant/après si le diff le montre clairement
- Inclure des chiffres concrets présents dans le diff (lignes supprimées, tables supprimées, endpoints ajoutés)
- Voix active, présent
Exemple :
Remplace le cache de session en mémoire dans auth.middleware.ts par un cache basé sur Redis (src/cache/redis.ts). Ajoute les méthodes get, set et invalidate au nouveau module Redis et encapsule UserService.getById() avec un TTL de 5 minutes. Supprime le cache basé sur Map, limité à un seul processus et responsable de divergences de session entre plusieurs instances.
Paragraphe 2 : Pourquoi c'est important (impact métier/produit)
- Qui en bénéficie et comment
- Quel problème cela résout ou quel risque cela réduit
- Si les messages de commit contiennent un "pourquoi", utiliser ce contexte
- S'il n'y a pas de "pourquoi" clair dans le diff ou les commits, omettre ce paragraphe plutôt que de deviner
Exemple :
Les utilisateurs accédant à l'endpoint /api/me en période de charge obtenaient des données de session incohérentes entre les instances du serveur, provoquant des erreurs 401 intermittentes. Ce changement rend l'état de session cohérent sur toutes les instances et réduit la charge de la base de données en éliminant une requête par appel authentifié.
Règles pour les deux paragraphes :
- Pas de tirets cadratins — utiliser une virgule ou un point
- Pas de remplissage : "cette PR", "ce changement", "comme vous pouvez le voir"
- Pas de résultats inventés. Ne mentionner que les impacts directement visibles dans le diff ou les messages de commit
- Si la PR est un simple refactoring sans changement de comportement, le dire explicitement : "Refactorise X en Y sans changement de comportement observable."
- Moins de 150 mots au total
Étape 4 : Auto-vérification
Avant de poster, vérifier :
- Le paragraphe 1 nomme des fichiers ou fonctions spécifiques du diff
- Pas de métriques ou résultats inventés
- Pas de tirets cadratins
- Pas de phrases de remplissage
- Moins de 150 mots au total
- S'il n'existe pas de "pourquoi" clair, le paragraphe 2 est omis plutôt que deviné
Corriger toute violation avant de poster.
Étape 5 : Poster en commentaire sur la PR
Présenter l'explication à l'utilisateur. Demander : "Prêt à poster ce commentaire sur la PR, ou souhaitez-vous d'abord le modifier ?"
Après confirmation, passer le corps via stdin pour gérer correctement les backticks, guillemets et sauts de ligne :
gh pr comment URL_OU_NUMERO_DE_PR --body-file - << 'EOF'
EXPLICATION_ICI
EOF
Après publication : "Commentaire ajouté. Consultez-le à : [url de l'étape 2]"
Si l'utilisateur dit "sortie uniquement", présenter l'explication dans un bloc de code pour copie manuelle sans publication.