jpgiannetti/roadwave
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: documenter migration et règles de contribution

Browse Source 
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
2026-02-08 19:54:30 +01:00
parent a29718a8e8
commit 5497ea793f
2 changed files with 677 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

457
docs/CONTRIBUTING.md Normal file
View File

@@ -0,0 +1,457 @@
# Guide de Contribution à la Documentation
Bienvenue ! Ce guide explique comment contribuer à la documentation RoadWave tout en respectant son architecture et ses conventions.
## Principes Fondamentaux
### 1. Source Unique de Vérité (Single Source of Truth)
Chaque information doit exister à **un seul endroit** :
- **Règles métier** → `docs/domains/[domain]/rules/*.md`
- **Features BDD** → `domains/[domain]/features/**/*.feature` (sources Gherkin)
- **Documentation BDD** → `docs/generated/bdd/` (générée automatiquement)
- **Entités** → `docs/domains/[domain]/entities/*.md`
- **États** → `docs/domains/[domain]/states/*.md`
- **Séquences** → `docs/domains/[domain]/sequences/*.md`
❌ **Ne jamais** dupliquer une information
✅ **Toujours** référencer via des liens
### 2. Langue : 100% Français
Tous les fichiers de documentation doivent être en français :
- ✅ Noms de fichiers en français (kebab-case)
- ✅ Contenu en français
- ✅ Navigation `mkdocs.yml` en français
- ⚠️ Exception : code backend en anglais (convention internationale)
### 3. Dossier `generated/` = Read-Only
Le dossier `docs/generated/` contient **exclusivement** des fichiers générés automatiquement.
❌ **Ne JAMAIS** créer de fichiers manuels dans `generated/`
❌ **Ne JAMAIS** éditer des fichiers dans `generated/`
✅ Modifier les sources (`.feature`) et regénérer
## Ajouter une Nouvelle Feature BDD
### Étape 1 : Créer le fichier `.feature`
```bash
# Créer dans le bon domaine
touch domains/[domain]/features/[category]/ma-feature.feature
```
**Exemple** : Feature de recherche dans le domaine recommendation
```bash
touch domains/recommendation/features/recherche/recherche-avancee.feature
```
### Étape 2 : Écrire la feature en Gherkin
```gherkin
# language: fr
Fonctionnalité: Recherche avancée de contenus
En tant qu'utilisateur
Je veux rechercher des contenus avec des filtres avancés
Afin de trouver exactement ce que je cherche
Contexte:
Étant donné que je suis connecté
Et que je suis sur la page de recherche
Scénario: Recherche par catégorie et distance
Quand je sélectionne la catégorie "Tourisme"
Et je définis un rayon de 10 km
Alors je vois uniquement les contenus de type "Tourisme"
Et tous les résultats sont à moins de 10 km
Scénario: Recherche avec filtres multiples
# ... autres scénarios
```
**Conventions Gherkin** :
- Langue française (`# language: fr`)
- Mots-clés : `Fonctionnalité`, `Scénario`, `Étant donné`, `Quand`, `Alors`
- Commentaires pour référencer les règles DDD
### Étape 3 : Regénérer la documentation
```bash
make bdd-docs
```
Cette commande :
1. Parse les fichiers `.feature`
2. Génère les `.md` dans `generated/bdd/`
3. Démarre le serveur MkDocs (http://localhost:8000)
### Étape 4 : Ajouter dans `mkdocs.yml`
Si la catégorie n'existe pas encore, l'ajouter :
```yaml
- '🎯 Recommendation':
# ...
- Tests BDD:
- 'Recherche':
- Recherche de contenu: generated/bdd/recommendation/features/recherche/recherche.md
- Recherche avancée: generated/bdd/recommendation/features/recherche/recherche-avancee.md # ← NOUVEAU
```
### Étape 5 : Commit
```bash
git add domains/recommendation/features/recherche/recherche-avancee.feature
git add mkdocs.yml
git commit -m "feat(bdd): ajouter feature recherche avancée
- Ajout recherche par catégorie et distance
- Ajout filtres multiples
- Couverture domaine recommendation"
```
## Ajouter une Règle Métier
### Étape 1 : Identifier le domaine
Déterminer dans quel domaine DDD se situe la règle :
- **Shared** : Authentification, RGPD, erreurs, profil
- **Recommendation** : Algorithme, jauges d'intérêt, recherche
- **Content** : Audio-guides, création, streaming
- **Moderation** : Signalements, validation, sanctions
- **Advertising** : Publicités, ciblage
- **Premium** : Abonnements, mode offline
- **Monetization** : Paiements, revenus créateurs
### Étape 2 : Créer ou éditer le fichier de règles
```bash
# Éditer fichier existant
vim domains/[domain]/rules/[theme].md
# Ou créer un nouveau fichier
touch domains/[domain]/rules/nouveau-theme.md
```
### Étape 3 : Documenter la règle
```markdown
# Règles - Nouveau Thème
## Contexte
Description du contexte métier...
## Règles
### Règle 1 : Titre de la règle
**Contexte** : Quand...
**Règle** : L'utilisateur doit/peut/ne peut pas...
**Justification** : Parce que...
**Exemple** :
- Cas nominal : ...
- Cas d'erreur : ...
### Règle 2 : Autre règle
...
## Liens avec d'autres domaines
- [Entité X](../entities/entite-x.md)
- [Séquence Y](../sequences/sequence-y.md)
- [ADR-XXX](../../adr/XXX-decision.md)
```
### Étape 4 : Créer les features BDD correspondantes
Les règles métier doivent être testables → créer des features BDD.
### Étape 5 : Ajouter dans `mkdocs.yml`
```yaml
- '🎙️ Content':
- Règles:
- Création & Publication: domains/content/rules/creation-publication.md
- Nouveau Thème: domains/content/rules/nouveau-theme.md # ← NOUVEAU
```
## Ajouter une Entité
### Créer le fichier
```bash
touch domains/[domain]/entities/nouvelle-entite.md
```
### Documenter l'entité
```markdown
# Entité : NouvelleThing
## Description
Brève description de l'entité...
## Attributs
| Attribut | Type | Description | Contraintes |
|----------|------|-------------|-------------|
| `id` | UUID | Identifiant unique | PK, NOT NULL |
| `name` | String | Nom de la chose | NOT NULL, max 255 |
| `created_at` | Timestamp | Date de création | NOT NULL |
## Relations
- **BelongsTo** : [User](../../../_shared/entities/users.md)
- **HasMany** : [Items](./items.md)
## États du Cycle de Vie
Voir [Lifecycle](../states/nouvelle-thing-lifecycle.md)
## Règles Métier
- [Règle de création](../rules/creation.md#nouvelle-thing)
- [Règle de validation](../rules/validation.md#nouvelle-thing)
## Implémentation Backend
**Module** : `backend/internal/[domain]/`
**Table** : `nouvelle_things`
**Repository** : `nouvelle_thing_repository.go`
Requêtes sqlc : `backend/queries/nouvelle_thing.sql`
```
### Ajouter dans `mkdocs.yml`
```yaml
- Entités:
- Vue d'ensemble: domains/[domain]/entities/vue-ensemble.md
- Nouvelle Entité: domains/[domain]/entities/nouvelle-entite.md # ← NOUVEAU
```
## Ajouter un Diagramme
### Diagrammes de Séquence
```bash
touch domains/[domain]/sequences/nouveau-processus.md
```
```markdown
# Séquence - Nouveau Processus
## Diagramme
\`\`\`mermaid
sequenceDiagram
participant U as Utilisateur
participant A as API
participant DB as Database
U->>A: POST /nouvelle-action
A->>DB: Vérifier permissions
DB-->>A: OK
A->>DB: INSERT nouvelle_thing
A-->>U: 201 Created
\`\`\`
## Légende
**Acteurs** :
- Utilisateur : Client de l'API
- API : Backend RoadWave
- Database : PostgreSQL
**Étapes clés** :
1. Vérification des permissions
2. Insertion en base
3. Retour confirmation
## Cas d'Erreur
### Permissions insuffisantes
...
### Contrainte violée
...
```
### Diagrammes d'États
```bash
touch domains/[domain]/states/nouvelle-thing-lifecycle.md
```
```markdown
# États - Lifecycle NouvelleThing
## Diagramme
\`\`\`mermaid
stateDiagram-v2
[*] --> Draft
Draft --> Pending: Submit
Pending --> Approved: Approve
Pending --> Rejected: Reject
Approved --> Published: Publish
Published --> Archived: Archive
Archived --> [*]
\`\`\`
## États
| État | Description | Transitions Possibles |
|------|-------------|----------------------|
| Draft | Création en cours | → Pending |
| Pending | En attente validation | → Approved, Rejected |
| Approved | Validé | → Published |
| Rejected | Refusé | → Draft (correction) |
| Published | Publié | → Archived |
| Archived | Archivé | (final) |
## Règles de Transition
### Draft → Pending
**Conditions** : Tous les champs obligatoires remplis
**Actions** : Notification modérateurs
```
## Conventions de Nommage
### Fichiers Markdown
```bash
# Format : kebab-case-francais.md
✅ export-donnees.md
✅ suppression-compte.md
✅ moderation-communautaire.md
✅ vue-ensemble.md
❌ data-export.md (anglais)
❌ entities-overview.md (anglais)
❌ ExportDonnees.md (PascalCase)
❌ export_donnees.md (snake_case)
```
### Fichiers Features
```bash
# Format : kebab-case-francais.feature
✅ signalement.feature
✅ jauge-initiale.feature
✅ creation-audio-guide.feature
❌ reporting.feature (anglais)
❌ initial-gauge.feature (anglais)
```
### Répertoires
```bash
# Format : kebab-case-anglais (convention internationale)
✅ features/
✅ interest-gauges/
✅ content-creation/
✅ rgpd-compliance/
```
## Vérifications Avant Commit
### Checklist
- [ ] Tous les fichiers sont en français (sauf code backend)
- [ ] Pas de fichiers dans `generated/` (seulement sources modifiées)
- [ ] Les liens internes fonctionnent
- [ ] `mkdocs.yml` mis à jour si nécessaire
- [ ] Features BDD regénérées (`make bdd-docs`)
- [ ] Message de commit descriptif
### Tester Localement
```bash
# Vérifier syntaxe YAML
python3 -c "import yaml; yaml.safe_load(open('mkdocs.yml'))"
# Tester la navigation
make docs-serve
# → http://localhost:8000
```
### Vérifier les Liens
```bash
# Chercher liens cassés vers anciens noms
grep -r "entities-overview\.md" docs/
grep -r "user-account-lifecycle\.md" docs/
grep -r "data-export\.md" docs/
# Ne devrait rien retourner
```
## Messages de Commit
### Format
```
type(scope): description courte
Corps optionnel avec détails...
Refs: #issue-number
```
### Types
- `feat(bdd)` : Nouvelle feature BDD
- `docs(rules)` : Nouvelle règle métier
- `docs(entity)` : Nouvelle entité
- `fix(link)` : Correction de lien
- `refactor(nav)` : Réorganisation navigation
### Exemples
```bash
# Feature BDD
git commit -m "feat(bdd): ajouter recherche avancée dans recommendation"
# Règle métier
git commit -m "docs(rules): documenter règles de modération préventive"
# Entité
git commit -m "docs(entity): ajouter entité Campaign pour advertising"
# Fix
git commit -m "fix(link): corriger lien vers vue-ensemble.md"
```
## Ressources
- **Architecture DDD** : [domains/README.md](domains/README.md)
- **Tests BDD** : [ADR-007](adr/007-tests-bdd.md)
- **Migration** : [MIGRATION.md](MIGRATION.md)
- **ADRs** : [adr/README.md](adr/README.md)
## Support
Questions ? Consultez :
1. Cette documentation
2. Les ADRs existants
3. Les exemples dans les domaines existants
4. L'équipe RoadWave
## Auteurs
- Équipe RoadWave
- Claude Sonnet 4.5 (documentation)
Dernière mise à jour : 2026-02-08

220
docs/MIGRATION.md Normal file
View 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