Dépôt canonique Forge et récupération de commits¶

Document opérationnel. Verrouille la procédure de contrôle du dépôt de travail avant tout ticket Forge, et la procédure officielle de récupération si des commits ont été faits hors du dépôt canonique (projet généré, clone temporaire, environnement WSL secondaire…).

Audience : contributeurs (humains et agents IA) qui s'apprêtent à ouvrir un ticket Forge ou à porter des commits faits par erreur dans un autre dépôt.

Origine : ticket GIT-RECOVERY-WORKFLOW-GUARD-001 — après la release 1.0.0-beta.11, plusieurs tickets ont été commités par erreur dans un projet généré WSL (~/Projets/forge-test-b11) avant d'être portés par patchs dans le dépôt canonique. Cette page rend la procédure officielle et reproductible.

1. Dépôt canonique Forge¶

Le seul dépôt de référence pour le framework Forge est :

Champ	Valeur attendue
Chemin local	`/home/roger/Projets/Forge`
Branche par défaut	`main` (ou une branche ticket issue de `main`)
Remote `origin` (fetch et push)	`git@github.com:caucrogeGit/Forge.git`
Working tree	propre avant démarrage d'un ticket

Tout commit Forge doit être créé dans ce dépôt. Aucun travail sur le framework ne doit être effectué dans :

un projet généré par forge new (présence d'un dossier mvc/ à plat sans la structure complète du dépôt framework) ;
un dossier nommé forge-test-*, forge-beta*, forge-sandbox-* ;
un clone temporaire posé dans /tmp/, un WSL secondaire, une VM d'essai ;
toute branche master (Forge utilise main exclusivement).

2. Checklist pré-ticket¶

À exécuter avant d'écrire la moindre ligne d'un nouveau ticket :

pwd
git status --short
git branch --show-current
git remote -v
git log -3 --oneline

Critères pour valider le dépôt courant comme Forge canonique :

pwd contient /home/roger/Projets/Forge ;
la branche courante est main ou une branche ticket (port/..., ticket/...) explicitement créée à partir de main ;
origin pointe sur git@github.com:caucrogeGit/Forge.git (fetch et push) ;
le working tree est propre (git status --short ne retourne rien).

Si l'un des critères n'est pas rempli, arrêter immédiatement. Ne pas continuer le ticket. Soit corriger le contexte (changer de dossier, basculer de branche, nettoyer le working tree), soit suivre la procédure de récupération de la section 4 si des commits ont déjà été créés hors du dépôt canonique.

3. Signes d'un mauvais dépôt¶

Indicateurs qui doivent déclencher un arrêt immédiat :

branche courante = master (Forge n'utilise pas master) ;
commit initial du type « based on Forge … » ou « generated by forge new » (c'est un projet généré, pas le framework) ;
chemin courant sous forge-test-*, forge-sandbox-*, /tmp/ ;
git remote -v ne fait pas apparaître caucrogeGit/Forge.git (ou pointe vers un fork, un mirror ou un dépôt local) ;
présence d'un dossier mvc/ sans les dossiers core/, forge_cli/, packages/, tests/, docs/ côte à côte (signe caractéristique d'un projet généré : seul mvc/ est extrait).

Dans tous ces cas, on n'est pas dans Forge canonique. Les modifications faites ici ne seront pas reflétées dans la release publique du framework tant qu'elles n'auront pas été portées explicitement.

4. Procédure officielle de récupération¶

À appliquer si des commits ont été faits par erreur dans un dépôt secondaire (projet généré, WSL local, clone temporaire) et doivent être portés dans Forge canonique.

4.1 Ne pas continuer dans le mauvais dépôt¶

Premier réflexe : arrêter d'ajouter des commits dans le dépôt fautif. Continuer ne ferait qu'augmenter la dette à porter et le risque de divergence.

4.2 Exporter les commits avec `git format-patch`¶

Dans le dépôt source (le mauvais) :

git format-patch <base>..<head> -o /tmp/forge-recovery-patches

<base> est le dernier commit présent aussi dans Forge canonique (souvent origin/main au moment où le dépôt secondaire a été créé). <head> est HEAD ou la branche locale fautive.

Les éventuels changements non commités (WIP) doivent être exportés séparément (par exemple via git diff > /tmp/forge-recovery-patches/wip.patch) et ne pas être appliqués automatiquement à l'étape 4.6 — ils sont revus manuellement.

4.3 Copier les patchs vers la machine canonique¶

Adapter l'hôte / l'utilisateur selon l'environnement :

scp /tmp/forge-recovery-patches/*.patch \
    roger@192.168.1.222:/tmp/forge-recovery-patches/

4.4 Créer une branche de portage dans Forge canonique¶

cd /home/roger/Projets/Forge
git switch main
git status --short                # doit être vide
git switch -c port/recovery-$(date +%Y%m%d)

Le préfixe port/recovery-YYYYMMDD rend la branche identifiable comme branche de portage temporaire.

4.5 Vérifier chaque patch avec `git apply --check`¶

Patch par patch, dans l'ordre d'export :

git apply --check /tmp/forge-recovery-patches/0001-xxx.patch

Si git apply --check échoue (conflits, contexte introuvable, fichiers absents), ne pas forcer. Relire le patch, comprendre la divergence, adapter manuellement.

4.6 Appliquer avec `git am` les patchs validés¶

git am /tmp/forge-recovery-patches/0001-xxx.patch

git am préserve auteur, date et message original. Les patchs WIP ne sont pas appliqués automatiquement : ils sont relus à la main, recoupés en commits propres, puis intégrés via des commits explicites.

4.7 Valider avec les contrôles canoniques¶

Avant la fusion dans main, lancer les cinq validations Forge :

.venv/bin/python -m pytest -x -q
.venv/bin/python -m compileall -q .
.venv/bin/python -m ruff check .
.venv/bin/python -m mkdocs build --strict
git diff --check

Pour un portage purement documentaire, restreindre la suite pytest à tests/meta (plus rapide) est acceptable, à condition que les commits portés ne touchent que de la documentation et des tests méta.

4.8 Fusionner en fast-forward dans `main`¶

git switch main
git merge --ff-only port/recovery-$(date +%Y%m%d)

Le --ff-only garantit qu'il n'y a pas de commit de merge implicite qui obscurcirait l'historique. Si le fast-forward échoue, c'est que main a divergé pendant le portage — rebaser la branche de portage sur main à jour, refaire les validations, puis retenter.

4.9 Pousser¶

git push origin main

Vérifier ensuite que les commits attendus apparaissent bien dans le log distant.

5. Interdits explicites¶

Pendant une récupération, jamais :

merger directement un projet généré dans Forge canonique (git merge <chemin-vers-projet-généré>) — la structure ne correspond pas ;
copier-coller un gros diff manuel sans audit patch par patch ;
appliquer un patch WIP automatiquement (git am wip.patch) — le WIP est revu à la main et recoupé en commits explicites ;
continuer un ticket si le dépôt courant est ambigu (échec d'un seul critère de la section 2) ;
travailler depuis un dossier forge-test-*, forge-sandbox-*, /tmp/ ou un projet généré pour modifier le core Forge ;
supprimer les patchs /tmp/forge-recovery-patches/ avant que les commits portés soient poussés et confirmés sur origin/main.

6. Pour aller plus loin¶

Conventions internes de Forge — patterns opérationnels (audit avant action, tests, code, doc).
Vue d'ensemble du contributeur — préparation de l'environnement, sélection du ticket, validations canoniques.
Procédure de release — pour les tags officiels, qui ne sont jamais créés depuis un dépôt secondaire.
CLAUDE.md (racine du dépôt) — briefing IA, mentionne cette page comme étape 0 obligatoire avant tout ticket.