jpgiannetti/roadwave
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
5497ea793f425d03ff48d7d40448055f2928fd14
roadwave/docs/MIGRATION.md
jpgiannetti 5497ea793f docs: documenter migration et règles de contribution 
Ajout de 2 fichiers de documentation :

MIGRATION.md :
- Liste complète des changements effectués
- Tableau de correspondance ancien → nouveau
- Métriques de la migration (21% → 100% features accessibles)
- Guide de rollback si nécessaire
- FAQ

CONTRIBUTING.md :
- Principes fondamentaux (source unique, français, generated/ read-only)
- Guide ajout feature BDD (étape par étape)
- Guide ajout règle métier
- Guide ajout entité et diagrammes
- Conventions de nommage
- Checklist avant commit
- Format des messages de commit
2026-02-08 19:54:30 +01:00

221 lines
6.5 KiB
Markdown
Raw Blame History

# Migration Documentation - Réorganisation 2026-02-08
Cette documentation liste tous les changements effectués lors de la réorganisation complète de la documentation RoadWave.
## Objectifs de la Migration
1. **Éliminer les redondances** : Supprimer les doublons de fichiers et la navigation duale
2. **Normaliser la langue** : 100% français pour la cohérence
3. **Intégrer BDD dans DDD** : Source unique de vérité avec navigation domaine-first
4. **Rendre accessible toutes les features** : 164 features BDD dans la navigation (vs 34 avant)
## Changements Effectués
### 1. Fusions de Fichiers Doublons
**Fichiers supprimés** (versions anglaises) :
| Fichier Supprimé | Fichier Conservé | Raison |
|-----------------|------------------|---------|
| `sequences/data-export.md` | `sequences/export-donnees.md` | Version française plus détaillée |
| `sequences/account-deletion.md` | `sequences/suppression-compte.md` | Version française plus détaillée |
### 2. Renommages EN → FR
**Entités** :
| Ancien Nom | Nouveau Nom |
|-----------|-------------|
| `entities-overview.md` | `vue-ensemble.md` |
**États (Lifecycles)** :
| Ancien Nom | Nouveau Nom |
|-----------|-------------|
| `user-account-lifecycle.md` | `compte-utilisateur.md` |
| `content-lifecycle.md` | `contenu.md` |
| `session-lifecycle.md` | `session.md` |
| `report-lifecycle.md` | `signalement.md` |
| `export-lifecycle.md` | `export-donnees.md` |
| `parental-consent-lifecycle.md` | `consentement-parental.md` |
| `account-deletion-lifecycle.md` | `suppression-compte.md` |
| `breach-incident-lifecycle.md` | `incident-breach.md` |
**Séquences** :
| Ancien Nom | Nouveau Nom |
|-----------|-------------|
| `authentication-flow.md` | `authentification.md` |
| `token-refresh.md` | `refresh-token.md` |
| `content-moderation.md` | `moderation-contenu.md` |
| `content-report.md` | `signalement.md` |
### 3. Réorganisation Navigation
**Changement majeur** : Suppression de la section "Tests BDD" autonome
**Avant** :
```yaml
- Domaines DDD:
- Shared: (avec Features BDD)
- Recommendation: (SANS Features BDD)
- Content: (SANS Features BDD)
- ...
- Tests BDD:
- Vue d'ensemble: generated/bdd/index.md
```
**Après** :
```yaml
- Domaines DDD:
- Shared:
- Tests BDD: (34 features)
- Recommendation:
- Tests BDD: (17 features) ← NOUVEAU
- Content:
- Tests BDD: (59 features) ← NOUVEAU
- Moderation:
- Tests BDD: (23 features) ← NOUVEAU
- Advertising:
- Tests BDD: (7 features) ← NOUVEAU
- Premium:
- Tests BDD: (16 features) ← NOUVEAU
- Monetization:
- Tests BDD: (8 features) ← NOUVEAU
```
**Résultat** : 164/164 features BDD accessibles (100% vs 21% avant)
### 4. Structure de Navigation par Domaine
Chaque domaine suit désormais cette structure cohérente :
```
Domaine X:
- Vue d'ensemble
- Règles métier
- Entités
- [États] (si applicable)
- [Séquences] (si applicable)
- [Diagrammes] (si applicable)
- Tests BDD ← AJOUTÉ pour tous les domaines
```
## Métriques de la Migration
| Métrique | Avant | Après | Amélioration |
|----------|-------|-------|--------------|
| Fichiers doublons | 4 | 0 | -100% |
| Features BDD accessibles | 34/164 (21%) | 164/164 (100%) | +379% |
| Domaines avec section BDD | 1/7 (14%) | 7/7 (100%) | +600% |
| Chemins vers BDD | 2 | 1 | Source unique |
| Langues mélangées | 2 (FR + EN) | 1 (FR) | Cohérence |
## Impact sur les Liens
Tous les liens internes ont été automatiquement mis à jour. Si vous avez des liens externes ou des bookmarks :
### Entités
```markdown
# Ancien lien (cassé)
docs/domains/_shared/entities/entities-overview.md
# Nouveau lien
docs/domains/_shared/entities/vue-ensemble.md
```
### États
```markdown
# Ancien lien (cassé)
docs/domains/_shared/states/user-account-lifecycle.md
# Nouveau lien
docs/domains/_shared/states/compte-utilisateur.md
```
### Séquences
```markdown
# Ancien lien (cassé)
docs/domains/_shared/sequences/data-export.md
# Nouveau lien
docs/domains/_shared/sequences/export-donnees.md
```
## Navigation vers les Features BDD
### Avant (34 features accessibles)
Pour accéder aux features BDD de Shared :
1. Domaines DDD → Shared → Features BDD
2. **OU** Tests BDD → Vue d'ensemble
Pour les autres domaines : **Impossible** (130 features inaccessibles)
### Après (164 features accessibles)
Pour accéder aux features BDD de n'importe quel domaine :
1. Domaines DDD → [Domaine] → Tests BDD
Un seul chemin, cohérent pour tous les domaines.
## Commits de la Migration
1. `docs: fusionner séquences dupliquées (garder versions FR)`
2. `docs: renommer fichiers EN→FR pour cohérence linguistique`
3. `docs: mettre à jour liens après renommages`
4. `docs: intégrer toutes les features BDD dans navigation DDD`
5. `docs: supprimer index.md manuels du dossier generated/bdd`
## Rollback (si nécessaire)
Pour revenir à l'état avant migration :
```bash
git checkout docs-before-refactor
# OU
git revert a29718a..4b28db3
```
Tag de sauvegarde : `docs-before-refactor`
## Questions Fréquentes
### Où sont passées les pages "Vue d'ensemble" des domaines BDD ?
Elles ont été supprimées car elles étaient dans le dossier `generated/` qui doit contenir uniquement les fichiers générés automatiquement par `scripts/generate-bdd-docs.py`. Les features sont directement accessibles dans la navigation.
### Pourquoi supprimer la section "Tests BDD" autonome ?
Pour établir une **source unique de vérité** : les tests BDD sont une vue testable des règles DDD, ils doivent donc être intégrés dans chaque domaine DDD, pas séparés.
### Comment trouver une feature BDD maintenant ?
1. Identifier le domaine concerné (content, recommendation, etc.)
2. Domaines DDD → [Domaine] → Tests BDD
3. Naviguer dans les catégories
### Les fichiers `.feature` sont-ils dans la navigation ?
Non. Seuls les fichiers générés (`.md` dans `generated/bdd/`) sont dans la navigation MkDocs. Les `.feature` sources sont dans `domains/[domain]/features/`.
## Prochaines Étapes
Pour maintenir cette organisation :
1. **Toujours** utiliser les noms français pour les nouveaux fichiers
2. **Ne jamais** créer de fichiers manuels dans `generated/`
3. **Ajouter** les nouvelles features dans `domains/[domain]/features/`
4. **Regénérer** avec `make bdd-docs` après ajout de features
5. **Consulter** `CONTRIBUTING.md` pour les règles de contribution
## Auteurs
- Claude Sonnet 4.5 (réorganisation)
- Équipe RoadWave (validation)
Date : 2026-02-08
Reference in New Issue View Git Blame Copy Permalink