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

# Créer dans le bon domaine
touch domains/[domain]/features/[category]/ma-feature.feature

Exemple : Feature de recherche dans le domaine recommendation

touch domains/recommendation/features/recherche/recherche-avancee.feature

Étape 2 : Écrire la feature en 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

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 :

- '🎯 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

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

# É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

# 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

- '🎙️ 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

touch domains/[domain]/entities/nouvelle-entite.md

Documenter l'entité

# 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

- 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

touch domains/[domain]/sequences/nouveau-processus.md

# 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

touch domains/[domain]/states/nouvelle-thing-lifecycle.md

# É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

# 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

# Format : kebab-case-francais.feature
✅ signalement.feature
✅ jauge-initiale.feature
✅ creation-audio-guide.feature

❌ reporting.feature (anglais)
❌ initial-gauge.feature (anglais)

Répertoires

# 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

# 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

# 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

# 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
• Tests BDD : ADR-007
• ADRs : 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