Conventions Git — Workflow et commits¶

Ce document est la reference pour le workflow Git de l'organisation. Il couvre le format des commits, le nommage des branches, le processus de pull request, la politique de merge et la Definition of Done. Tous les repositories de l'organisation doivent suivre ces conventions.

Portee¶

Ce standard s'applique a tous les contributeurs (humains et agents IA) sur tous les repositories de l'organisation. Aucune exception n'est toleree sur le format des commits et des branches.

Langue obligatoire — Anglais

Tous les contenus visibles dans GitHub — issues, pull requests, branches, commits et commentaires — doivent etre rediges exclusivement en anglais.

Format de commit¶

Structure¶

Chaque message de commit suit le format :

<Type>(<Context>): <ShortMessage>

Le contexte entre parentheses est obligatoire. Ne jamais l'omettre.

Types autorises¶

Les memes types s'appliquent aux commits, issues et pull requests.

Type	Description	Exemple
`Feat`	Nouvelle fonctionnalite	`Feat(Auth): Add JWT token refresh`
`Fix`	Correction de bug	`Fix(Api): Resolve null pointer in request parser`
`Refactor`	Restructuration sans changement fonctionnel	`Refactor(Core): Extract validation logic to dedicated class`
`Perf`	Amelioration de performance	`Perf(Cache): Optimize LRU eviction algorithm`
`Build`	Changements du systeme de build	`Build(Dependencies): Upgrade logging library to v2.0`
`Docs`	Documentation uniquement	`Docs(Api): Add OpenAPI schema for auth endpoints`
`Style`	Formatage, espaces (aucun changement logique)	`Style(Core): Apply formatter to all source files`
`Chore`	Maintenance, outillage, `.gitignore`	`Chore(Tooling): Update pre-commit hooks`
`Test`	Ajout ou mise a jour de tests	`Test(Auth): Add unit tests for token validation`
`CI`	Changements CI/CD	`CI(Pipeline): Add code coverage reporting`
`Breaking`	Changement cassant necessitant une migration	`Breaking(Api): Remove deprecated v1 endpoints`

Commits de merge automatiques

Les commits de merge generes automatiquement par Git (Merge branch ...) sont acceptes par le linter mais ne doivent jamais etre ecrits manuellement.

Contexte¶

Le contexte est le nom du composant ou module modifie, en PascalCase.

Contexte	Usage
Nom du module	`Core`, `Auth`, `Api`, `Gateway`
Build system	`Build`, `Dependencies`
Outillage	`Tooling`, `Scripts`
Documentation	`Docs`
Infrastructure	`Infra`, `Deploy`

Chaque repository definit sa propre liste de contextes valides dans son CLAUDE.md.

Commits atomiques¶

Regle	Explication
Un changement logique par commit	Eviter les "mega-commits" qui modifient plusieurs systemes non lies
Commiter chaque unite logique separement	L'historique reste un journal clair des modifications
Le message decrit QUOI, pas COMMENT	"Add JWT refresh" et non "Modify AuthService.java line 42"

Branches¶

Branches permanentes¶

Le projet utilise un modele Git Flow simplifie avec deux branches permanentes.

main (protegee, releases/versions)
  └── dev (integration)
       ├── epic/50-authentication    ← branche d'integration epic
       │    ├── feat/51-login-page   ← story ciblant la branche epic
       │    └── fix/52-token-expiry  ← story ciblant la branche epic
       └── feat/89-standalone-story  ← story sans epic, cible dev

Branche	Role	Protection
`main`	Releases de production	Recoit uniquement des merges depuis `dev`
`dev`	Integration	Les PRs d'epic et stories orphelines ciblent `dev`

Branches courtes¶

Format : <type>/<issue-num>-<description-courte>

Prefixe	Usage	Creee depuis
`epic/`	Branche d'integration epic (regroupe les stories liees)	`dev`
`feat/`	Nouvelle feature ou story	`dev` ou branche `epic/` parente
`fix/`	Correction de bug	`dev` ou branche `epic/` parente
`refactor/`	Refactoring	`dev`
`docs/`	Documentation	`dev`
`ci/`	CI/CD	`dev`
`test/`	Tests	`dev`

Les autres types de commit (Chore, Perf, Style, Build, Breaking) utilisent feat/ comme prefixe de branche par defaut.

Exemples :

epic/50-authentication-system
feat/51-login-page
feat/42-user-authentication
fix/78-login-timeout
ci/55-coverage-report
docs/63-api-reference
refactor/91-extract-validation

Regles¶

Les branches epic sont creees depuis dev
Les branches de story sont creees depuis la branche epic/ parente si elle existe, sinon depuis dev
La description utilise le kebab-case
Le numero d'issue lie la branche a son ticket
La branche est supprimee apres merge
Pas de minuscules dans le prefixe (Feat/ est interdit, feat/ est correct)

Conventions alternatives en entreprise¶

Convention	Exemple	Contexte typique
`type/issue-desc`	`feat/89-auth-flow`	Startups, PME, open source (notre choix)
`type/JIRA-ID-desc`	`feat/APEX-89-auth-flow`	Grands groupes avec Jira
`user/type/desc`	`simia/feat/auth-flow`	Grandes equipes (evite les collisions)
`type/desc` (sans numero)	`feat/auth-flow`	Petites equipes informelles

Pull Requests¶

Titre¶

Meme format que les commits et issues :

<Type>(<Context>): <ShortMessage>

Creation de PR avec `mem pr`¶

La commande mem pr est l'outil principal pour creer et mettre a jour les PRs. Elle s'execute depuis la branche de la story et :

Detecte l'issue liee a la branche (via le numero dans le nom de branche).
Detecte la branche cible (branche epic parente via les sub-issues GitHub, ou dev par defaut).
Genere le titre et le body de la PR a partir des informations de l'issue.
Cree la PR (ou la met a jour si elle existe deja — la commande est idempotente).

Cela garantit la coherence entre l'issue et la PR, et evite la duplication d'informations.

Le body de la PR est ecrase par mem pr

Ne jamais ecrire d'informations directement dans la description de la PR — elles seront perdues au prochain mem pr. Toujours modifier l'issue source.

Modifier une PR en cours¶

Tant que la PR n'a pas ete review, si le developpeur modifie l'issue (ajout de details, correction de specs, etc.), il relance mem pr pour mettre a jour la PR.

Regle : 1 story = 1 PR¶

Chaque issue de type story donne lieu a exactement 1 PR. Pas de PR multi-stories, pas de story sans PR.

Politique de merge¶

Regle	Detail
Cible story	Les PRs de story ciblent la branche epic parente si elle existe, sinon `dev`
Cible epic	Les PRs d'epic ciblent `dev` une fois toutes les stories mergees
Interdit	Jamais `main` directement
Strategie story/epic	Merge commit pour les PRs vers `epic/` ou `dev` (preserve l'historique des commits individuels)
Strategie release	Squash merge uniquement pour `dev` → `main` (un seul commit de release)
Approbations	2 approbations requises avant merge
Qui merge	Tout membre de l'equipe peut merger une fois les 2 approbations obtenues
Post-merge	La branche est supprimee apres merge
Release	Quand `dev` est stable, une PR `dev` -> `main` est ouverte pour la release
Detection auto	La commande `mem pr` detecte automatiquement la branche epic via les sub-issues GitHub

Titre des issues¶

Les titres d'issues suivent le meme format que les commits et PRs :

<Type>(<Context>): <ShortMessage>

Regle stricte : une issue ne peut pas quitter le status Backlog (vers Ready ou au-dela) si son titre ne respecte pas ce format. Corriger le titre d'abord.

Exemples :

Feat(Auth): Add OAuth2 provider support
Fix(Api): Resolve race condition in connection pool
Build(Core): Configure dependency detection
Docs(Api): Add endpoint documentation

Definition of Done¶

Checklist que toute PR doit satisfaire avant merge. S'applique en plus des criteres d'acceptance specifiques a la story.

Code¶

Compile sans warning avec les flags de production du projet
Respecte les conventions de formatage et de lint du repository
Fonctions < 100 lignes, < 6 parametres

Tests¶

Tests unitaires ajoutes/mis a jour pour le code modifie
La suite de tests passe a 100%
Pas de regression de couverture

CI¶

Tous les checks CI passent

Review¶

PR reviewee et approuvee par 2 membres de l'equipe
Commentaires de review resolus
Commits au format <Type>(<Context>): <ShortMessage>

Documentation¶

Documentation sur les nouvelles APIs publiques
CLAUDE.md mis a jour si l'architecture change

Enablers¶

Si cette story est un enabler : verifier que les stories debloquees peuvent passer en Ready
Mettre a jour les checkboxes ## Enablers dans les issues debloquees
Retirer le label blocked des issues debloquees

Processus de code review¶

Retours sur GitHub uniquement¶

Les retours de review se font exclusivement via l'interface GitHub, en commentant directement sur les lignes ou blocs de code concernes. Pas de retours par Discord.

Un commentaire de review doit etre precis : expliquer clairement le probleme ou l'amelioration proposee, et si possible suggerer une solution. Ce n'est pas au reviewer de faire le travail de developpement — si suggerer une solution demande trop de travail, expliquer le probleme suffit.

Commentaire recapitulatif¶

Une fois la review terminee, le developpeur et le reviewer discutent des retours. Une fois d'accord, le developpeur poste un commentaire recapitulatif global sur la PR avec 3 sections :

## Review Summary

### A. Retours qui seront traites
- [ ] Retour 1 (commentaire #link)
- [ ] Retour 2 (commentaire #link)

### B. Retours acceptes en l'etat
- Retour 3 — **Raison** : [pourquoi acceptable]

### C. Retours reportes a une nouvelle issue
- Retour 4 — **Issue** : #NNN — **Raison** : [pourquoi reporte]

Les retours de la section A sont coches au fur et a mesure de leur traitement. Une fois tout traite, le reviewer re-review et approuve.

Si les modifications invalident l'issue¶

Si les retours de review entrainent des changements qui invalident certaines informations de l'issue, ajouter un commentaire sur l'issue indiquant d'aller voir dans la PR les modifications.

Workflow complet d'une story¶

1. CREATION
   Issue creee avec le template adapte (Story, Bug, Spike).
   Labels : type + domaine + enabler (si applicable).
   Status : Backlog.

2. REFINEMENT
   Template complete, criteres d'acceptance clarifies.
   Estimation en story points.
   Enablers identifies.
   Si cross-repo : ping du proprietaire du repo pour validation.
   Si tous les enablers sont Done -> Status : Ready.

3. SPRINT PLANNING
   L'equipe selectionne les stories Ready pour le sprint.
   Iteration mise a jour.
   Les devs claim leurs stories.

4. DEVELOPPEMENT
   Le dev claim -> Status : In Progress.
   Cree sa branche : feat/<issue>-description.
   Developpe, commite au format <Type>(<Context>): <ShortMessage>.
   Coche les checkboxes ## Tasks et ## Acceptance Criteria dans l'issue.

5. PULL REQUEST
   `mem pr` cree la PR liee automatiquement -> In Review.
   Modifications avant review ? -> modifier l'issue, relancer `mem pr`.

6. REVIEW
   2 reviewers (dont le proprietaire du repo si cross-repo).
   Retours via commentaires GitHub sur le code.
   Commentaire recapitulatif global (sections A/B/C).
   Traitement des retours, re-review, approbation.

7. DONE
   PR mergee -> Issue fermee -> Status : Done (auto).
   Si enabler : debloquer les issues dependantes.