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
This commit is contained in:
jpgiannetti
220
docs/MIGRATION.md
Normal file
220
docs/MIGRATION.md
Normal file
@@ -0,0 +1,220 @@
|
||||
# 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
Block a user