Arc 2 Quête 10

Le Protocole des Guildes

Pull Requests, revue de code et workflows

Le Maître Archiviste te conduit dans la Grande Salle du Conseil. Autour d'une table ronde en obsidienne, des sièges vides portent les blasons de différentes guildes. Au centre, un immense registre est enchaîné à la table - le Registre Central des Chroniques. Personne ne peut y écrire directement.

« Archiviste, tu maîtrises désormais les branches, les fusions, la réécriture et les portails distants. Mais il te reste à comprendre le Protocole - les règles sacrées qui permettent aux guildes de travailler ensemble sans chaos. Aucun Archiviste n'écrit directement dans le Registre Central. Chacun propose ses modifications, et le Grand Conseil les examine avant de les accepter. C'est le fondement de toute collaboration. »

Pourquoi ne pas écrire directement sur main ?

Imagine : dix Archivistes poussent simultanément leurs modifications sur main. L'un casse le code, l'autre introduit un bug, un troisième écrase le travail du quatrième.

C'est le chaos. Et c'est exactement ce qui arrive dans les projets réels quand tout le monde fait git push directement sur la branche principale.

Les risques du push direct sur main :

  • Code cassé : quelqu'un pousse du code non testé, tout le monde est bloqué
  • Conflits en cascade : les merges deviennent un cauchemar
  • Pas de revue : personne ne vérifie la qualité avant l'intégration
  • Pas de traçabilité : impossible de savoir pourquoi un changement a été fait
  • Rollback difficile : si le problème est détecté tard, revenir en arrière est pénible

Dans les guildes les plus disciplinées, la branche main est sacrée. Personne n'y touche directement. Tout passe par le Protocole.

Le workflow Feature Branch

C'est le flux de travail le plus courant dans le monde professionnel. Le principe est simple :

1 Créer une branche git switch -c
➡
2 Travailler commits
➡
3 Pousser git push
➡
4 Pull Request plateforme
➡
5 Revue + Merge git merge 
main:     A---B-----------F (merge)
               \         /
feature:        C---D---E

Chaque étape a son importance. Voyons-les en détail.

Qu'est-ce qu'une Pull Request ?

Une Pull Request (PR) - appelée Merge Request (MR) sur GitLab et Forgejo - est une demande formelle de fusion d'une branche dans une autre.

C'est l'équivalent numérique d'une pétition au Grand Conseil : tu présentes tes modifications, tu expliques pourquoi elles sont nécessaires, et le Conseil examine ton travail avant de l'approuver.

Ce que contient une Pull Request

  • Un titre clair et descriptif
  • Une description qui explique le "pourquoi" et le "comment"
  • La liste des commits inclus
  • Le diff - les modifications ligne par ligne
  • Des commentaires et discussions de revue
  • Un statut : ouverte, approuvée, fusionnée, fermée

Les Pull Requests ne font pas partie de Git. C'est une fonctionnalité ajoutée par les plateformes (GitHub, GitLab, Forgejo, Bitbucket). Mais le workflow sous-jacent (branche + merge) est 100% Git.

Anatomie d'une bonne Pull Request

Le titre

Le titre doit être court, clair et descriptif. Il doit dire ce que fait la PR, pas comment.

Bons exemples

  • Ajouter la validation des formulaires d'inscription
  • Corriger le crash au démarrage sur Windows
  • Mettre à jour les dépendances de sécurité

Mauvais exemples

  • Modifs - trop vague
  • fix - ne dit rien
  • WIP branche de Jean - pas un titre

La description

La description est ta chance d'expliquer :

  • Pourquoi ce changement est nécessaire
  • Ce qui a changé (résumé des modifications)
  • Comment tester (étapes pour vérifier que ça marche)
  • Ce qui n'est pas inclus (si pertinent)

La taille

Une bonne PR est petite et focalisée. Elle fait une seule chose. Vise 50 à 200 lignes de diff - pas 2000.

« Un bon parchemin présente une idée claire. Une pétition qui mélange dix sujets différents finit toujours au fond d'une pile, ignorée par le Conseil. »

La revue de code

La revue de code (code review) est le moment où un ou plusieurs collègues examinent tes modifications avant la fusion.

Que chercher lors d'une revue ?

  • Le code fonctionne-t-il ? - Logique correcte, pas de bugs évidents
  • Le code est-il lisible ? - Noms clairs, structure compréhensible
  • Le code est-il testé ? - Y a-t-il des tests pour les nouveaux comportements ?
  • Le code suit-il les conventions ? - Style, nommage, architecture du projet
  • Le code est-il nécessaire ? - Pas de code mort, pas de duplication inutile

Donner un bon feedback

Constructif

  • "On pourrait simplifier cette boucle avec un map()"
  • "Pourquoi ce choix ? Je suis curieux du contexte"
  • nit: pour les détails cosmétiques
  • Propose des solutions, pas juste des critiques

Destructif

  • "C'est nul"
  • "C'est faux" (sans expliquer pourquoi)
  • Critiquer sans proposer d'alternative
  • Mélanger l'important et le cosmétique

Recevoir du feedback

  • Ne le prends pas personnellement - la revue porte sur le code, pas sur toi
  • Réponds aux commentaires - même si c'est pour dire "bonne idée, je corrige"
  • Apprends de chaque revue - c'est une des meilleures façons de progresser

« Le Conseil ne juge pas l'Archiviste. Il juge le parchemin. Un bon Archiviste accueille les critiques avec gratitude - elles rendent ses chroniques meilleures. »

Le workflow Fork

Quand tu veux contribuer à un projet qui ne t'appartient pas (un projet open source par exemple), tu ne peux pas créer de branche directement sur le repo original. Tu utilises alors le workflow fork :

  1. Fork : tu crées une copie du repo sur ton propre compte
  2. Clone : tu clones ton fork en local
  3. Branche : tu crées une branche de travail
  4. Commits : tu fais tes modifications
  5. Push : tu pousses sur ton fork
  6. Pull Request : tu ouvres une PR depuis ton fork vers le repo original
Repo original (upstream)     Ton fork (origin)       Ton PC (local)
         |                        |                       |
         |    fork                |                       |
         |----------------------->|                       |
         |                        |    clone              |
         |                        |---------------------->|
         |                        |                       | branch + commits
         |                        |    push               |
         |                        |<----------------------|
         |    Pull Request        |                       |
         |<-----------------------|                       |

C'est le flux standard pour contribuer à des projets open source sur GitHub, GitLab ou Forgejo. Le propriétaire du repo original reçoit ta PR et décide s'il l'accepte.

Stratégies de branchement

Comment organiser les branches dans un projet ? Il existe plusieurs stratégies. Voici les trois principales.

GitHub Flow Recommandé

La stratégie la plus simple et la plus courante :

  • main est toujours déployable
  • Pour chaque travail, tu crées une branche depuis main
  • Tu ouvres une Pull Request
  • Après revue et approbation, tu fusionnes dans main
main:     A---B-------E---F-------I
               \     /     \     /
feature-1:      C---D       G---H

Idéal pour : la plupart des projets, déploiement continu.

Git Flow

Une stratégie plus structurée avec plusieurs branches permanentes :

  • main : le code en production
  • develop : la branche d'intégration
  • feature/* : branches de fonctionnalités (depuis develop)
  • release/* : préparation d'une version (depuis develop)
  • hotfix/* : corrections urgentes (depuis main)

Idéal pour : projets avec des versions numérotées (v1.0, v2.0...).

Attention : complexe, beaucoup de branches à gérer. Ne l'utilise pas sans bonne raison.

Trunk-Based Development

Les développeurs travaillent directement sur main (le "trunk") avec des branches très courtes (quelques heures max). Les fonctionnalités inachevées sont cachées derrière des feature flags.

Idéal pour : grandes équipes avec une infrastructure de tests très solide (Google, Facebook).

« Le GitHub Flow est le Protocole que je recommande aux jeunes guildes. Il est simple, efficace, et suffisant pour la grande majorité des projets. Tu n'as pas besoin de la complexité de Git Flow avant d'avoir une bonne raison. »

Protéger la branche main

Sur les plateformes (GitHub, GitLab, Forgejo), tu peux configurer des règles de protection pour la branche main :

  • Interdire le push direct : tout doit passer par une Pull Request
  • Exiger une revue : au moins N personnes doivent approuver
  • Exiger des tests verts : les tests automatiques doivent passer
  • Interdire le force push : empêcher la réécriture de l'historique
  • Exiger un historique linéaire : forcer le rebase avant merge

Ces règles sont configurées dans les paramètres du repo sur la plateforme, pas dans Git lui-même. C'est une couche de sécurité supplémentaire au-dessus du Protocole.

Template de Pull Request

Tu peux créer un fichier .github/PULL_REQUEST_TEMPLATE.md (sur GitHub/Forgejo) à la racine de ton projet. Quand quelqu'un ouvre une Pull Request, ce template pré-remplit la description.

## Description
<!-- Décris ce que fait cette PR et pourquoi -->

## Type de changement
- [ ] Nouvelle fonctionnalité
- [ ] Correction de bug
- [ ] Refactoring
- [ ] Documentation

## Comment tester
<!-- Étapes pour vérifier que ça marche -->

## Checklist
- [ ] Le code compile sans erreur
- [ ] Les tests passent
- [ ] La documentation est à jour

C'est un excellent moyen de standardiser la qualité des PR dans une équipe. Tout le monde sait quoi remplir, et les revues sont plus efficaces.

Exercice pratique - Simuler le Protocole

Simule le workflow complet d'une Pull Request en local :

  1. Crée un repo avec un premier commit sur main
  2. Crée une branche proposition/ameliorer-defenses
  3. Fais 2 commits sur cette branche
  4. Examine les changements depuis main (simule la revue)
  5. Fusionne avec --no-ff pour créer un commit de merge
  6. Supprime la branche fusionnée
  7. Lance le script de vérification

Étape 1 - Créer le dépôt et le premier commit

mkdir protocole-des-guildes
cd protocole-des-guildes
git init -b main
echo "# Defenses du Royaume" > defenses.txt
echo "" >> defenses.txt
echo "Les defenses actuelles protegent la cite." >> defenses.txt
git add defenses.txt
git commit -m "Creer le registre des defenses du royaume"

Étape 2 - Créer la branche de proposition

git switch -c proposition/ameliorer-defenses

Étape 3 - Faire des commits sur la branche

Premier commit - ajouter des fortifications :

echo "" >> defenses.txt
echo "## Fortifications" >> defenses.txt
echo "- Renforcer les murailles nord avec de la pierre enchantee" >> defenses.txt
echo "- Ajouter des tours de guet aux quatre coins" >> defenses.txt
git add defenses.txt
git commit -m "Ajouter les propositions de fortifications"

Deuxième commit - ajouter des formations :

echo "" >> defenses.txt
echo "## Formations" >> defenses.txt
echo "- Former les gardes au combat magique" >> defenses.txt
echo "- Etablir des rondes nocturnes doublees" >> defenses.txt
git add defenses.txt
git commit -m "Ajouter les propositions de formations"

Étape 4 - Examiner les modifications (simuler la revue)

# Revenir sur main
git switch main

# Voir la liste des commits de la proposition
git log main..proposition/ameliorer-defenses --oneline

# Voir le détail des modifications
git diff main..proposition/ameliorer-defenses

C'est exactement ce que fait une plateforme quand elle affiche le diff d'une Pull Request. Tu fais la même chose en ligne de commande.

Étape 5 - Fusionner avec --no-ff

L'option --no-ff (no fast-forward) force la création d'un commit de merge, même si un fast-forward serait possible. C'est important car :

  • Ça crée un point de repère dans l'historique
  • On voit clairement où la branche a été intégrée
  • Ça correspond à ce que font les plateformes quand elles fusionnent une PR
git merge --no-ff proposition/ameliorer-defenses -m "Fusionner la proposition d'amelioration des defenses"

Étape 6 - Supprimer la branche fusionnée

git branch -d proposition/ameliorer-defenses

Étape 7 - Vérifier l'historique

git log --oneline --graph

Tu devrais voir quelque chose comme :

*   abc1234 Fusionner la proposition d'amelioration des defenses
|\
| * def5678 Ajouter les propositions de formations
| * ghi9012 Ajouter les propositions de fortifications
|/
* jkl3456 Creer le registre des defenses du royaume

Étape 8 - Lancer la vérification

bash verifier.sh
.\verifier.ps1

Récapitulatif des commandes

Commande Description
git switch -c branche Créer une branche de travail
git log main..branche Voir les commits d'une branche
git diff main..branche Voir le diff d'une branche
git merge --no-ff branche Fusionner avec commit de merge
git branch -d branche Supprimer une branche fusionnée

Le Maître Archiviste se lève et te fait face. Pour la première fois, il ne te regarde plus comme un apprenti.

« Tu as maîtrisé le Protocole des Guildes. Tu sais proposer des modifications, les examiner, les fusionner proprement. Tu comprends pourquoi personne n'écrit directement dans le Registre Central, et tu connais les stratégies qui permettent aux guildes de collaborer à grande échelle. »

Il pose la main sur ton épaule.

« L'Arc des Branches du Destin est achevé. Tu es désormais un Archiviste à part entière - capable de travailler seul ou en équipe, de gérer des branches et des fusions, de contribuer à n'importe quel projet. Mais ton voyage ne fait que commencer. »

Il te conduit vers une porte que tu n'avais jamais remarquée. Derrière, un escalier descend dans les profondeurs de la Citadelle.

« Au-delà de cette porte se trouvent les Arts Anciens - les techniques avancées que seuls les Maîtres utilisent. Tu y apprendras à mettre de côté ton travail en cours, à cueillir un commit précis dans une autre branche, à traquer un bug dans l'historique, et bien d'autres secrets. Mais ça, c'est pour le prochain chapitre de ton histoire. »