Workflows

Git

Commits — Conventional Commits

Format strict :

type(scope): description #issue

Type	Usage
feat	Nouvelle fonctionnalité
fix	Correction de bug
refactor	Réorganisation sans changement de comportement
chore	Maintenance, outillage, dépendances
docs	Documentation
style	Formatage, whitespace, lint (pas de logique)
test	Ajout ou modification de tests
perf	Amélioration de performance
build	Build system, bundler, deps de prod
ci	CI/CD

Référence d'issue obligatoire quand une issue GitLab existe. Format #N :

feat(api): ajoute endpoint POST /enrollments #67
fix(frontend): corrige redirection après login #58
refactor(frontend): découpe LearnerDashboardPage (817 → 52 lignes)
chore: retire le dossier .idea/ du suivi git

Branches

• Branche principale : master
• Branches de travail : branches d'intégration longue durée, une par domaine métier, regroupées sous deux namespaces correspondant à la couche applicative.

Le préfixe <couche>/ regroupe visuellement les branches dans GitLab. Chaque branche est permanente : les travaux d'un domaine s'y accumulent (en référençant l'issue dans chaque commit), puis sont remontés vers master par MR périodique.

Namespace	Branche	Périmètre
backend/	backend/auth	Authentification, JWT, refresh tokens, RBAC
	backend/learning	Cours, modules/chapitres/sections, inscriptions, progression, quiz, certificats
	backend/payments	Paiement (stub MVP, gateways v1.1)
	backend/back-office	Espace admin + dashboard formatrice
frontend/	frontend/learner	Espace apprenante
	frontend/teacher	Espace formatrice
	frontend/admin	Espace admin
	frontend/public	Zone publique (landing, auth, catalogue public)
	frontend/shared	Socle transverse : package @app/ui, structure des apps, config build

Un nouveau domaine ⇒ nouvelle branche d'intégration sous le namespace adéquat (même modèle longue durée).

Branches opérationnelles

En marge des branches de domaine, deux branches longue durée à finalité non-métier :

Branche	Finalité
florent-dev	Tests en local. Les essais locaux se font ici, plus sur master. Resynchronisée depuis master (ou une branche de domaine) selon le besoin.
devops	Déploiement en environnement de staging. Porte la config de déploiement / infra ; suit master.

Ces branches sont hors namespace frontend/·backend/ (elles ne portent pas un domaine métier) — c'est volontaire.

Politiques de push

Action	Règle
Push direct sur master	Autorisé pour le mainteneur, sinon passer par MR
git push --force sur branche partagée	Jamais sans validation explicite
--no-verify (skip hooks)	Jamais — corriger la cause du hook qui échoue
git mv pour les renommages	Toujours, pour préserver l'historique

Commits destructifs

git reset --hard, git clean -f, git branch -D, git push --force : jamais sans OK explicite. Pour une erreur de commit déjà partagé, créer un nouveau commit correctif plutôt qu'un --amend.

Secrets

Ne jamais commiter .env, clés, tokens, credentials. Le fichier .env.example sert de template avec des valeurs factices.

GitLab

Référentiel

Clé	Valeur
Instance	gitlab.id2real.net
Repo	comlan.azankpe/e-learning
project_id	168

Authentification API

Token GitLab stocké dans .env racine (ignoré par git) :

GITLAB_TOKEN=<personal-access-token>
GITLAB_PROJECT_ID=168

Scope minimal recommandé pour le token : api, read_repository. Rotation régulière conseillée.

Issues

• Référencer l'issue dans chaque commit qui la concerne
• Types d'issue usuels : task, issue, incident
• Activer confidential: true pour les issues sensibles (analyse stratégique, sécurité)

Labels conventionnels

Catégorie	Valeurs	Usage
Domaine	frontend, backend, infra, docs	1 par issue
Contexte	navigation, analyse, architecture, securite, ops	1-2 par issue
Sévérité	severity:high, severity:medium, severity:low	1 par issue
Nature	fix, feat, refactor	1 par issue
Rôle sprint	sprint, chapeau	Sur l'issue chapeau uniquement

Milestones

Un milestone regroupe un ensemble cohérent d'issues : un sprint, une décision structurante, un chantier. Format : <Préfixe> — <périmètre> (ex. Nav — zone publique).

Workflow type

1. Création de l'issue côté GitLab (manuellement ou via API)
2. Travail sur la branche d'intégration du domaine concerné (ex. backend/learning), selon le label Domaine de l'issue
3. Commits référencés #N
4. MR périodique de la branche de domaine vers master (regroupe les travaux du domaine prêts à être livrés)
5. Merge après revue
6. Fermeture automatique via keyword dans le commit (Closes #N)

La branche de domaine n'est pas supprimée après la MR : elle reste vivante et continue d'accueillir les travaux suivants du domaine.

Sprint planning

Méthodologie pour transformer une analyse ou une cartographie en un sprint GitLab structuré (milestone + issue chapeau + sous-issues).

Quand l'appliquer

• Réorganisation structurelle (cartographie navigation, audit UX, refactor multi-pages)
• Analyse comparative produisant verdict + actions (ex : choix de stack)
• Audit transverse (sécurité, perf, accessibilité, i18n)
• Toute tâche qui produit plus de 5 findings à suivre

Pour moins de 5 items, un commit direct ou une seule issue suffit.

Les 7 étapes

1. Définir le périmètre

• Zone, feature, module ou dimension à couvrir
• Compact : max ~15 sous-issues par sprint
• Si trop large : découper en sous-périmètres (ex. 4 sprints par zone au lieu d'un sprint géant)

2. Explorer

• Séquentiel si les éléments sont couplés ou si on apprend en avançant
• Parallélisé (agents Explore en parallèle) si les éléments sont indépendants — gain de temps
• Toujours lire les fichiers racines critiques d'abord (ex : App.tsx pour connaître les routes valides)

3. Documenter dans un doc canonique

Chaque workflow a un document dans docs/. Le doc contient :

• Légende des statuts (OK, DEAD, TODO, BUG, etc.)
• Vue globale (diagramme ou table)
• Une section par unité explorée avec structure, inventaire, findings, diagramme
• Un inventaire consolidé des findings
• Tables par sprint avec placeholder pour les IIDs

4. Consolider en issues regroupées

Règle : 1 issue = 1 thème cohérent, pas 1 finding = 1 issue. Regrouper :

• Patterns répétés (ex : "logos non cliquables ×5 occurrences" = 1 issue)
• Bugs de même cause
• Actions complémentaires sur un même écran

Ne pas regrouper si :

• Les fix demandent des compétences ou zones très différentes
• La priorité diffère beaucoup
• La taille deviendrait > 1 jour-dev

Attribuer à chaque issue : un code court (P1, L5, T7, A3), une sévérité, une nature.

5. Créer sur GitLab

Ordre strict :

1. Créer le milestone (<Préfixe> — <périmètre>)
2. Créer l'issue chapeau avec table des sous-issues (placeholder #PENDING)
3. Créer les sous-issues en batch
4. Mettre à jour l'issue chapeau avec les vrais IIDs

6. Rattacher les IIDs dans le doc canonique

Mettre à jour la table du sprint pour lister les IIDs réels.

7. Commit + push

Commit unique : docs(<canonique>): rattache les N issues GitLab du sprint <nom>. Push à la fin de chaque sprint planifié, pas à chaque micro-étape.

Templates

Issue chapeau

## Objectif
<Description en 1-2 phrases.>

## Périmètre
<N> sous-issues couvrant : <thème 1>, <thème 2>, ...

## Sous-issues
| # | Titre | Issue |
|---|---|---|
| <code1> | <titre> | `#PENDING` |

## Sévérités
- Haute : <codes>
- Moyenne : <codes>
- Basse : <codes>

## Hors scope
- <exclusion 1>

## Références
- Cartographie : `docs/<canonique>.md`
- Milestone : `<nom>`

Sous-issue

## Contexte
Réf cartographie : `docs/<canonique>.md` §<section>.
Parent : issue chapeau du sprint `<nom>`.

## Problème
<Description précise avec chemins/fichiers/lignes.>

## Tâches
1. <action>
2. <action>

## Critère d'acceptation
- [ ] <vérifiable>
- [ ] Doc canonique mise à jour.

## Hors scope
<Ce qu'on ne traite pas ici.>

Décisions architecturales (ADR)

Les décisions structurantes (choix de stack, refonte d'un domaine, abandon d'une option) sont consignées comme Architecture Decision Records dans Décisions.

Chaque ADR suit le format :

• Contexte : pourquoi cette décision est nécessaire
• Décision : ce qui est acté
• Conséquences : ce que cela implique (positif comme négatif)

Les ADR sont datées et immuables une fois publiées : si on revient sur une décision, on crée une nouvelle ADR qui supersède l'ancienne, on ne réécrit pas l'historique.