Workflow Git et pull requests

Le Clos des Eucalyptus utilise deux dépôts et un projet GitHub unifié. develop est la branche d’intégration ; main représente la production. Les changements ordinaires passent par une branche et une PR.

Avant de commencer

1. Lisez l’issue, ses critères d’acceptation et ses relations.
2. Vérifiez les dépendances et les PR déjà ouvertes.
3. Confirmez le dépôt propriétaire du changement.
4. Exécutez make status à la racine du workspace.
5. Actualisez origin/develop sans écraser un travail local.

Un label cross-stack signale une coordination ; il n’autorise pas automatiquement à modifier les deux dépôts. Le contenu de l’issue détermine le périmètre.

Branches

Usage	Convention	Base
Fonctionnalité dirigée par un utilisateur	feature/<issue>-<slug>	develop
Tâche autonome planifiée	codex/issue-<issue>-<slug>	develop
Release	release/<version>	develop
Correctif production	hotfix/<slug>	main

Pour un lot cross-stack, utilisez le même suffixe dans web et backend.

Worktrees

Un worktree évite de changer la branche, l’index ou les fichiers du checkout utilisé par le développeur :

git -C web worktree add /tmp/harmony-web-123 -b feature/123-exemple origin/develop
git -C backend worktree add /tmp/harmony-backend-123 -b feature/123-exemple origin/develop

Vérifiez toujours la cible exacte avant de retirer un worktree. Ne supprimez jamais un worktree qui contient des changements non commités appartenant à quelqu’un d’autre.

Statuts du projet

Statut	Signification
Backlog	identifié mais pas planifié pour exécution
Ready	planifié et sans décision manquante
In progress	branche créée et travail réellement commencé
Blocked	intervention externe nécessaire après démarrage
In review	toutes les PR attendues sont liées et prêtes à relire
Done	fermeture issue/automatisation après merge

Le label codex-ready autorise une tâche planifiée seulement lorsque l’issue est aussi Ready. Une epic de suivi reste au backlog sauf si tout son périmètre constitue volontairement un seul lot.

Commits

• Un commit traite une préoccupation cohérente.
• Le message explique l’intention : feat:, fix:, docs:, test:, chore:.
• N’incluez pas de fichiers générés ignorés, secrets ou changements étrangers.
• Vérifiez git diff --check, le statut et la validation avant le commit final.
• Ne réécrivez pas l’historique d’une branche déjà relue sans nécessité convenue.

Pull request

La PR cible develop, commence en draft et contient :

• résumé fonctionnel ;
• fichiers ou domaines importants ;
• preuve des validations ;
• notes de migration ou de déploiement ;
• lien de fermeture Closes #<numéro> ;
• lien vers la PR associée lorsque le lot traverse les deux dépôts.

Vérifiez que GitHub affiche la closing reference dans les deux sens. Passez ensuite la PR en Ready for review et l’issue en In review.

Lot parent avec sous-tâches

Une seule PR peut regrouper plusieurs sous-tâches lorsque :

• elles forment un incrément atomique ;
• leur ordre impose une livraison commune ;
• la taille reste relisible ;
• la PR lie explicitement chaque issue ;
• aucune sous-tâche ne nécessite un déploiement ou une validation indépendante.

Une epic purement organisationnelle ne doit pas devenir une PR géante. Séparez les changements qui peuvent être livrés et annulés indépendamment.

Cross-stack

Pour deux PR coordonnées :

1. créez les branches correspondantes depuis chaque develop ;
2. faites évoluer OpenAPI dans la PR backend ;
3. copiez l’instantané du contrat dans la PR web si nécessaire ;
4. rendez chaque dépôt compatible avec l’ordre de déploiement prévu ;
5. exécutez make verify dans les deux dépôts et make e2e à la racine ;
6. liez les PR dans leur description ;
7. ne passez l’issue en review que lorsque les deux PR sont prêtes.

Corriger une review

1. Vérifiez que le commentaire concerne le SHA courant et qu’il est applicable.
2. Reproduisez le problème ou démontrez le chemin d’exécution.
3. Corrigez uniquement le finding et ses tests nécessaires.
4. Relancez les validations proportionnées au risque.
5. Poussez un commit supplémentaire et demandez une nouvelle review.

Ne répondez pas à une review en masquant une erreur avec un fallback silencieux, un type any ou un retry global.

Ce que le workflow ne fait pas automatiquement

Une tâche d’implémentation ou de correction ne fusionne pas la PR, ne force-push pas, ne supprime pas la branche distante et ne déploie pas. La fermeture et le statut Done résultent du merge et des automatisations GitHub prévues.