Rédiger de bons PR et README

Pourquoi la rédaction technique est importante

Dans un code review, votre description de PR est le point d’entrée pour le relecteur. Une bonne description permet de :

✅ Aider le relecteur à comprendre rapidement ce que vous avez fait
✅ Réduire les allers-retours de questions
✅ Montrer que vous réfléchissez en profondeur
✅ Vous faire gagner du temps 3 mois plus tard quand vous consultez l’historique

Structure standard d’une description PR : What/Why/How/Testing

1. What (ce qui a été fait)

Résumé concis en une phrase.

Refactor authentication flow to support OAuth2 and magic link sign-up

Expressions clés :

Add X — nouvelle fonctionnalité
Fix X — correction de bug
Refactor X — réécriture de code (sans changer la fonctionnalité)
Optimize X — amélioration des performances
Implement X — implémentation d’un design

2. Why (pourquoi c’est fait)

La partie la plus souvent négligée. Expliquez le contexte et la motivation.

Why:
- Users requested passwordless sign-up option
- Current session-based auth doesn't scale to multiple domains
- OAuth2 is industry standard for enterprise integrations

Indicateurs d’un bon Why :

✅ Mention de la justification métier (besoin utilisateur, performance, maintenabilité)
✅ Explication de pourquoi la solution actuelle est insuffisante
✅ Explication de pourquoi cette solution est meilleure

3. How (comment c’est fait)

Vue d’ensemble technique de haut niveau.

How:
1. Created JWT service using Web Crypto API for signing/verification
2. Replaced SessionMiddleware with AuthMiddleware that validates JWT
3. Added OAuth2 routes for Google/GitHub sign-in

Breaking changes:
- Moved user auth state from server session to JWT (stateless)
- Clients now need to store and send JWT in Authorization header

Expressions clés :

Created X using Y — choix technique
Replaced X with Y — migration
Breaking changes — changements non rétrocompatibles

4. Testing (comment c’est testé)

Testing:
- Manual testing: Verified OAuth2 sign-in with Google and GitHub accounts
- Existing auth tests pass (147 tests)
- Added 23 new tests for JWT and OAuth2 flows

Template de description PR

Copiez ceci, remplissez les blancs :

## What
[résumé en une phrase]

## Why
- [raison 1]
- [raison 2]

## How
1. [changement 1]
2. [changement 2]

## Testing
- [vos tests]
- [les résultats]

## Related
Closes #123

Pièges grammaticaux en rédaction technique

1. Les temps verbaux (erreur la plus courante)

Règle : présent pour ce que fait le code, passé pour les changements apportés

Incorrect	Correct
”The function was created to handle X"	"The function handles X"
"The code will validate input"	"The code validates input”

2. La voix passive excessive

Règle : l’anglais préfère la voix active

Passif (fréquent chez les francophones)	Actif (meilleur)
“The JWT is generated by the server"	"The server generates the JWT"
"Breaking changes were introduced"	"This PR introduces breaking changes”

3. Nuances entre synonymes

Mot	Usage
Add	Nouvelle fonctionnalité inexistante : “Add OAuth2 support”
Fix	Corriger un bug : “Fix race condition in cache”
Refactor	Améliorer le code sans changer la fonctionnalité
Optimize	Améliorer les performances

Liste de contrôle rapide pour une PR

Avant d’envoyer la PR, vérifiez :

La section What explique clairement le changement
La section Why a une justification métier ou technique
La section How donne une vue d’ensemble du design
La section Testing indique la couverture de tests
Pas de voix passive excessive
Les temps verbaux sont cohérents
Lien vers les issues associées (si applicable)