roadwave/docs/adr/022-strategie-cicd-monorepo.md

# ADR-022 : Stratégie CI/CD avec Path Filters pour Monorepo

**Statut** : Accepté (non implémenté)
**Date** : 2026-02-01

## Contexte

RoadWave est organisé en monorepo contenant backend Go, mobile Flutter, documentation et features BDD ([ADR-014](014-organisation-monorepo.md)). Sans optimisation, chaque commit déclencherait **tous** les builds (backend + mobile + docs), même si seul un composant a changé.

**Problématique** :

- ❌ Temps de CI/CD inutilement longs (rebuild complet ~15 min)
- ❌ Gaspillage de ressources GitHub Actions
- ❌ Ralentissement du feedback développeur
- ❌ Coûts CI/CD élevés pour changements isolés

**Exemple** : Modification d'un fichier markdown dans `/docs` déclenche les tests backend (5 min) + tests mobile (8 min) + build (2 min) alors que seule la validation docs (~30s) est nécessaire.

## Décision

**Workflows GitHub Actions séparés** avec **path filters** pour rebuild sélectif basé sur les fichiers modifiés.

## Alternatives considérées

| Option | Optimisation | Complexité | Maintenance | Coût CI |
|--------|--------------|------------|-------------|---------|
| **Workflows séparés + path filters** | Excellente (~70%) | Faible | Simple | Minimal |
| Workflow monolithique | Nulle | Très faible | Simple | Élevé |
| Turborepo/Nx orchestration | Bonne (~50%) | Élevée | Complexe | Moyen |
| Multirepo (repos séparés) | Excellente | Élevée | Complexe | Variable |

## Architecture

### Structure Workflows

```
.github/workflows/
├── backend.yml    # Backend Go (tests, lint, build)
├── mobile.yml     # Mobile Flutter (tests, lint, build)
└── shared.yml     # Docs + code partagé (validation, génération)
```

### Configuration Path Filters

#### Workflow Backend (`backend.yml`)

**Déclencheurs** :

- Branches : `main`, `develop`
- Chemins surveillés :
  - `backend/**` : Code Go, migrations, configuration
  - `features/api/**` : Features BDD des tests API
  - `features/e2e/**` : Features BDD end-to-end impliquant le backend
  - `.github/workflows/backend.yml` : Modifications du workflow lui-même

**Jobs exécutés** :

- **Tests unitaires** : Exécution `go test` sur tous les packages
- **Tests d'intégration** : Utilisation de Testcontainers avec PostgreSQL/PostGIS
- **Tests BDD** : Exécution Godog sur features `api/` et `e2e/`
- **Lint** : Vérification golangci-lint
- **Build** : Compilation binaire production (dépend de tous les jobs précédents)

**Environnement** : Ubuntu latest, Go 1.21+

---

#### Workflow Mobile (`mobile.yml`)

**Déclencheurs** :

- Branches : `main`, `develop`
- Chemins surveillés :
  - `mobile/**` : Code Flutter/Dart, assets, configuration
  - `features/ui/**` : Features BDD des tests UI
  - `features/e2e/**` : Features BDD end-to-end impliquant le mobile
  - `.github/workflows/mobile.yml` : Modifications du workflow lui-même

**Jobs exécutés** :

- **Tests unitaires** : Exécution `flutter test` sur widgets et logique métier
- **Tests d'intégration** : Tests d'intégration Flutter (interactions UI complexes)
- **Lint** : Analyse statique `flutter analyze`
- **Build Android** : Compilation APK release (dépend des tests)
- **Build iOS** : Compilation IPA release sans codesign (dépend des tests)

**Environnement** :

- Tests/Lint/Build Android : Ubuntu latest
- Build iOS : macOS latest (requis pour Xcode)
- Flutter 3.16.0+

---

#### Workflow Shared (`shared.yml`)

**Déclencheurs** :

- Branches : `main`, `develop`
- Chemins surveillés :
  - `docs/**` : ADR, règles métier, documentation technique
  - `shared/**` : Contrats API, types partagés
  - `.github/workflows/shared.yml` : Modifications du workflow lui-même

**Jobs exécutés** :

- **Validation documentation** : Build MkDocs en mode strict (détecte erreurs markdown)
- **Vérification liens** : Validation des liens internes/externes dans documentation
- **Tests code partagé** : Exécution tests si du code partagé backend-mobile existe

**Environnement** : Ubuntu latest, Python 3.11+

---

### Matrice de Déclenchement

| Modification | Backend | Mobile | Shared | Temps total |
|-------------|---------|--------|--------|-------------|
| `backend/internal/auth/service.go` | ✅ | ❌ | ❌ | ~5 min |
| `mobile/lib/screens/home.dart` | ❌ | ✅ | ❌ | ~8 min |
| `features/api/authentication/*.feature` | ✅ | ❌ | ❌ | ~5 min |
| `features/ui/audio-guides/*.feature` | ❌ | ✅ | ❌ | ~8 min |
| `features/e2e/abonnements/*.feature` | ✅ | ✅ | ❌ | ~13 min (parallèle) |
| `docs/adr/016-email.md` | ❌ | ❌ | ✅ | ~30s |
| **Commit mixte (backend + mobile + docs)** | ✅ | ✅ | ✅ | ~13 min (parallèle) |

**Économie de temps** :

- Commit backend-only : ~5 min (vs 15 min sans path filters) = **67% plus rapide**
- Commit docs-only : ~30s (vs 15 min) = **97% plus rapide**

### Cas Particulier : Features E2E

Les tests end-to-end dans `/features/e2e/` **déclenchent les deux workflows** (backend ET mobile) car ils testent l'intégration complète :

**Exemples de features E2E** :

- `features/e2e/abonnements/` : Formulaire mobile → API Zitadel → API RoadWave → Mangopay → Confirmation UI
- `features/e2e/error-handling/` : Perte réseau → Fallback mode offline → Reprise auto après reconnexion

**Justification** : Les features E2E valident le contrat backend-mobile, donc les deux doivent être testés.

---

## Justification

### Avantages

✅ **Rebuild sélectif** : changement backend → seulement backend rebuild (~5 min au lieu de 15 min)

✅ **Économie de temps CI** : ~70% de réduction sur commits isolés (backend-only ou mobile-only)

✅ **Économie de coûts** : GitHub Actions facturé à la minute → réduction proportionnelle des coûts

✅ **Parallélisation** : workflows indépendants exécutés en parallèle par GitHub Actions

✅ **Features E2E** : déclenchent backend ET mobile → cohérence end-to-end garantie

✅ **Feedback rapide** : développeur backend voit uniquement résultats backend (moins de bruit)

✅ **Scalabilité** : ajout de nouveaux composants (admin panel, worker, etc.) = nouveau workflow isolé

### Inconvénients

❌ **Duplication config** : certains éléments (checkout, cache) dupliqués entre workflows

❌ **Maintenance** : 3 workflows à maintenir au lieu de 1

❌ **Complexité initiale** : setup plus complexe que workflow monolithique

**Mitigation** :

- Utiliser des **composite actions** pour partager la config commune
- Documentation claire dans ce ADR
- Coût initial faible (~2h setup) vs gains à long terme importants

---

## Implémentation

### Prérequis

- ✅ Code backend implémenté avec tests unitaires + intégration
- ✅ Code mobile implémenté avec tests Flutter
- ✅ Step definitions BDD implémentées pour `api/`, `ui/`, `e2e/`
- ✅ Catégorisation features BDD en `/features/{api,ui,e2e}` ([ADR-007](007-tests-bdd.md))

### Plan d'Implémentation

**Phase 1** : Setup workflows de base (~1h)

- Créer `backend.yml` avec jobs test + lint + build
- Créer `mobile.yml` avec jobs test + lint + build
- Créer `shared.yml` avec validation docs

**Phase 2** : Configuration path filters (~30 min)

- Ajouter `paths:` à chaque workflow
- Tester avec commits isolés (backend-only, mobile-only, docs-only)

**Phase 3** : Optimisations (~30 min)

- Ajouter caching (Go modules, Flutter dependencies, node_modules)
- Créer composite actions pour config partagée
- Ajouter badges status dans README

**Effort total estimé** : ~2h

### Validation

**Scénarios de test à valider** :

1. **Commit backend uniquement** : Modifications dans `/backend` → Vérifier exécution isolée de `backend.yml`
2. **Commit mobile uniquement** : Modifications dans `/mobile` → Vérifier exécution isolée de `mobile.yml`
3. **Commit features E2E** : Modifications dans `/features/e2e` → Vérifier exécution conjointe de `backend.yml` ET `mobile.yml`
4. **Commit documentation uniquement** : Modifications dans `/docs` → Vérifier exécution isolée de `shared.yml`
5. **Commit mixte** : Modifications backend + mobile + docs → Vérifier exécution des 3 workflows en parallèle

**Vérifications** : Consulter l'onglet "Actions" de GitHub pour confirmer quels workflows se sont déclenchés.

---

## Conséquences

### Positives

- **Productivité développeur** : feedback 3x plus rapide sur commits isolés
- **Coûts réduits** : ~70% d'économie sur minutes GitHub Actions
- **Meilleure expérience PR** : reviews plus rapides, moins d'attente CI
- **Scalabilité** : facile d'ajouter nouveaux composants (worker, admin, etc.)

### Négatives

- **Maintenance** : 3 workflows à maintenir vs 1
- **Setup initial** : ~2h vs ~30 min pour workflow simple
- **Complexité** : nécessite compréhension path filters GitHub Actions

### Risques

⚠️ **Faux négatifs** : path filter mal configuré → test non exécuté → bug en production

**Mitigation** :

- Features E2E déclenchent toujours backend + mobile (safety net)
- Tests de validation dans le plan d'implémentation
- Review obligatoire des modifications de workflows

---

## Références

- [ADR-007 - Tests BDD et Catégorisation Features](007-tests-bdd.md)
- [ADR-014 - Organisation Monorepo](014-organisation-monorepo.md)
- [GitHub Actions - Path Filters](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore)
- [Monorepo CI/CD Best Practices](https://monorepo.tools/#ci-cd)

---

## Statut d'Implémentation

**Actuel** : **Documenté mais non implémenté**

**Quand** : Lors du Sprint d'implémentation backend/mobile (code production)

**Pourquoi reporté** : Le projet est actuellement en phase de documentation uniquement. Aucun code backend/mobile n'est implémenté, donc pas de tests à exécuter. L'implémentation CI/CD sera faite lors du développement.

**Prochaines étapes** :
1. Implémenter code backend avec tests
2. Implémenter code mobile avec tests
3. Implémenter step definitions BDD
4. Créer workflows CI/CD selon ce ADR
5. Valider avec commits de test