roadwave/docs/CONTRIBUTING.md

# 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)
- **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