# Règles de documentation ## Principes généraux - **DOC-001** — La documentation structurée réside sous `docs/`. - **DOC-002** — `docs/000-README.md` est l'entrée de navigation documentaire. - **DOC-003** — Les documents normatifs résident sous `docs/rules/`. - **DOC-004** — Les documents d'architecture résident sous `docs/architecture/`. - **DOC-005** — Les documents de validation résident sous `docs/validation/`. - **DOC-006** — Les documents internes sont en français ; code, symboles et extraits techniques conservent leur langue naturelle. - **DOC-007** — Les tableaux Markdown suivent le format contrôlé par `scripts/audit_markdown_tables.py`. - **DOC-009** — La ligne séparatrice d'un tableau explicite l'alignement sémantique de chaque colonne : `:---` pour le texte aligné à gauche, `---:` pour les valeurs numériques alignées à droite et `:---:` pour une valeur courte dont le centrage est réellement pertinent. - **DOC-010** — Une colonne textuelle n'est pas centrée uniquement pour des raisons esthétiques ; les matrices documentaires utilisent par défaut l'alignement gauche explicite. - **DOC-011** — Les tableaux d'un même document conservent une convention d'alignement cohérente par type de donnée. - **DOC-008** — Deux lignes blanches consécutives sont interdites hors blocs de code. ## Catégories documentaires - **DOC-CAT-001** — `docs/ideas/` contient des idées, variantes ou pistes non engagées. Une idée n'est ni une réservation architecturale, ni un engagement de roadmap, ni une exigence. - **DOC-CAT-002** — `docs/studies/` contient des analyses construites destinées à comparer des solutions, évaluer une piste ou préparer une décision. Une étude reste non normative. - **DOC-CAT-003** — `docs/architecture/` contient uniquement des orientations ou décisions architecturales retenues. Une possibilité encore ouverte reste dans `ideas/` ou `studies/`. - **DOC-CAT-004** — `docs/rules/` contient les normes obligatoires du dépôt. Une décision d'architecture ne devient une règle que lorsqu'une contrainte durable et vérifiable doit être imposée. - **DOC-CAT-005** — `docs/objectives/` décrit les objectifs produit et techniques ; il ne remplace ni la roadmap ni les règles. - **DOC-CAT-006** — Les documents spécialisés existants (`games/`, `engine/`, `monetization/`, `services/`, `development/`, `testing/`, `validation/`) conservent leur rôle fonctionnel et ne servent pas de dépôt générique d'idées. - **DOC-CAT-007** — Une information peut mûrir de `idea` vers `study`, puis vers une décision d'architecture ou une réservation de capability ; ce passage est explicite et n'est jamais déduit de la seule présence d'un texte. - **DOC-CAT-008** — Une étude peut conclure à `retained`, `deferred`, `rejected` ou `needs-poc` sans créer automatiquement une capability, une crate ou une entrée de roadmap. ## Nomenclature documentaire - **DOC-NAME-001** — Les documents thématiques utilisent un préfixe numérique local à leur répertoire suivi d'un nom descriptif stable, par exemple `003-AUTH_OPTIONS.md`. - **DOC-NAME-002** — La séquence numérique est indépendante dans chaque répertoire documentaire. - **DOC-NAME-003** — Une fois un document livré, son numéro n'est pas renuméroté uniquement pour réordonner visuellement la documentation. - **DOC-NAME-004** — Un statut n'est pas encodé dans le nom de fichier. Les changements de statut ne provoquent donc pas de renommage mécanique. - **DOC-NAME-005** — Les noms de fichiers restent en anglais technique lorsqu'ils désignent un concept de projet ; le corps documentaire reste en français. - **DOC-NAME-006** — Le `README.md` racine du dépôt conserve ce nom canonique. Les README imposés ou naturels à une crate/package peuvent également conserver `README.md`. - **DOC-NAME-007** — Dans un répertoire documentaire destiné à contenir plusieurs fichiers Markdown, le point d'entrée porte le nom `000-README.md` afin d'être trié en premier. - **DOC-NAME-008** — Un nouveau répertoire documentaire multi-fichiers ne crée pas de `README.md` concurrent à `000-README.md`. ## Listes de tâches et d'état - **DOC-TASK-001** — Toute liste Markdown qui représente durablement des tâches, objectifs ou éléments suivis utilise les marqueurs `( )`, `(x)`, `(d)` et `(c)` plutôt que les task lists Markdown `[ ]` / `[x]`. - **DOC-TASK-002** — `( )` signifie `planned`, `(x)` signifie `completed`, `(d)` signifie `deferred` et `(c)` signifie `cancelled`. - **DOC-TASK-003** — Une liste purement descriptive n'utilise pas artificiellement ces marqueurs. - **DOC-TASK-004** — Les règles spécialisées d'un document peuvent préciser la sémantique ou la traçabilité des marqueurs sans introduire un autre alphabet de statuts. ## ROADMAP - **DOC-RMAP-001** — `ROADMAP.md` décrit le planning durable : objectifs prévus, réalisés, reportés ou annulés. Il ne suit pas le détail des prereleases et fixes. - **DOC-RMAP-002** — Le ROADMAP utilise les marqueurs de suivi canoniques définis par `DOC-TASK-*`. - **DOC-RMAP-003** — Les statuts s'appliquent aux lignes de scope et non automatiquement à une version entière. - **DOC-RMAP-004** — Une version peut être entièrement décrite par une seule ligne ou être ventilée en plusieurs lignes lorsque son scope a plusieurs devenirs. - **DOC-RMAP-005** — Une même version peut apparaître sur plusieurs lignes lorsque des sous-ensembles de son scope ont des devenirs différents. - **DOC-RMAP-006** — Une ligne `(x)` décrit uniquement ce qui a effectivement été livré dans la version concernée. - **DOC-RMAP-007** — Lorsqu'une partie du scope est reportée, elle reçoit sa propre ligne `(d)`. La destination est indiquée par `→ ` lorsqu'elle est connue, sinon par `→ target TBD`. - **DOC-RMAP-008** — Lorsqu'un élément reporté est replanifié dans une version cible, la nouvelle ligne peut indiquer `← deferred from ` afin d'assurer une traçabilité bidirectionnelle. - **DOC-RMAP-009** — Lorsqu'une partie du scope est annulée, elle reçoit sa propre ligne `(c)` ; une annulation partielle n'annule pas les éléments effectivement livrés. - **DOC-RMAP-010** — Une version stable clôturée ne conserve aucune ligne `( )` sous son numéro : tout scope initial doit être classé `(x)`, `(d)` ou `(c)`. - **DOC-RMAP-011** — Les lignes `(d)` et `(c)` restent dans la roadmap comme historique du planning et ne sont pas supprimées pour réécrire rétroactivement le plan. - **DOC-RMAP-012** — `ROADMAP.md` n'est pas modifié mécaniquement à chaque delta ; il change lorsque le périmètre, l'ordre, les objectifs ou le devenir d'un scope évoluent réellement. ## CHANGELOG - **DOC-CHG-001** — `CHANGELOG.md` est une synthèse de publication, pas un journal de développement. - **DOC-CHG-002** — Les `pre.*`, `alpha.*`, `beta.*` et leurs `.fix.*` ne créent normalement aucune entrée de changelog. - **DOC-CHG-003** — Le changelog est mis à jour à partir des jalons `rc.*` et pour chaque release stable. - **DOC-CHG-004** — Une entrée RC résume l'état candidat à publication ; l'entrée stable résume le résultat effectivement publié. - **DOC-CHG-005** — Les détails intermédiaires de construction, corrections et validations restent dans `deltas/` et `history/`. - **DOC-CHG-006** — Une ancienne entrée de changelog devenue incompatible avec cette politique peut être migrée une fois vers `deltas/` / `history/` existants sans prétendre que l'ancien historique n'a jamais existé. ## Deltas et historique - **DOC-DELTA-001** — Un fichier sous `deltas//` décrit exactement la tranche livrée, son état de base et ses validations attendues ; il est immuable après livraison. - **DOC-HIST-001** — L'historique transitoire validé réside sous `history//` avec un fichier immuable par jalon accepté. - **DOC-HIST-002** — Une entrée `history/` n'est créée qu'après validation du jalon qu'elle décrit ; le résultat d'une validation future n'est jamais pré-écrit. - **DOC-HIST-003** — Le delta suivant, ou le fix suivant lorsqu'il existe, crée l'entrée `history/` du dernier jalon définitivement validé si elle n'existe pas encore. - **DOC-HIST-004** — `history/` et `deltas/` ont des rôles distincts : `deltas/` décrit une livraison candidate et sa validation attendue ; `history/` enregistre le résultat accepté et durable. ## Validation documentaire - **DOC-VAL-001** — Une gate Markdown ou un audit syntaxique valide la forme des documents, jamais leur exactitude fonctionnelle, leur exhaustivité ni leur acceptation. - **DOC-VAL-002** — Une prerelease principalement documentaire reste candidate tant que son contenu n'a pas été relu et accepté humainement. - **DOC-VAL-003** — Une version de conception peut utiliser plusieurs `pre.N` successives uniquement pour permettre revue, correction, complément et maturation documentaire. - **DOC-VAL-004** — Cargo, Gradle, packaging et smoke tests ne sont requis pour une prerelease documentaire que si le delta modifie du code, une configuration de build/runtime ou un contrat susceptible de les affecter. - **DOC-VAL-005** — Le document de delta énumère les validations applicables ; l'absence volontaire d'une gate technique doit découler du scope réel, pas d'un raccourci. - **DOC-VAL-006** — Une version documentaire n'est promue en `rc` ou stable qu'après validation explicite de son contenu, même si tous les audits automatisés sont propres. ## Maturation des idées et capabilities - **DOC-MAT-001** — La chaîne de maturation conceptuelle de référence est `Idea → Study → Architectural decision → Reserved capability → Planned → Implemented`. - **DOC-MAT-002** — Une branche peut s'arrêter en `Deferred` ou `Rejected` à n'importe quelle étape pertinente. - **DOC-MAT-003** — `Reserved` signifie que le concept et sa place architecturale sont reconnus sans engagement d'implémentation ni de version. - **DOC-MAT-004** — `Planned` signifie qu'une implémentation est affectée à une version ou un jalon de roadmap. - **DOC-MAT-005** — `Experimental` signifie qu'un POC ou une implémentation d'évaluation existe ou est explicitement planifié ; ce statut ne remplace pas `Reserved` pour une simple possibilité. - **DOC-MAT-006** — Une idée purement spéculative ne devient pas une capability réservée uniquement pour préserver une possibilité future. ## Immutabilité des deltas - **DOC-DELTA-002** — Un fichier `deltas/**/*.md` livré est immuable sur le fond. Il ne reçoit jamais ultérieurement de nouveau scope, de nouvelle règle, de nouvelle validation, de nouveau résultat ou de nouvelle justification. - **DOC-DELTA-003** — Une correction strictement non sémantique d'un delta livré est autorisée uniquement pour la forme : orthographe, typographie, alignement de tableau ou correction mécanique équivalente. - **DOC-DELTA-004** — Toute correction autorisée par `DOC-DELTA-003` incrémente le numéro `version` d'en-tête du fichier corrigé. - **DOC-DELTA-005** — Toute correction sémantique ou tout ajout produit un nouveau delta ou un nouveau `.fix.N` ; l'ancien delta reste inchangé. - **DOC-DELTA-006** — Un fichier `deltas/**/*.delete.txt` fait partie du contrat de livraison et doit être documenté explicitement par le fichier Markdown du même delta. - **DOC-DELTA-007** — Un manifest `*.delete.txt` contient uniquement des chemins relatifs à la racine, un par ligne. Le delta associé documente la raison des suppressions et la commande d'application. ## Versions d'en-tête - **DOC-HEAD-001** — Tout fichier géré par le projet qui possède un en-tête `version` incrémente ce numéro lors de toute modification réelle de contenu. - **DOC-HEAD-002** — Une modification réelle inclut ajout, suppression, déplacement, reformulation, changement de valeur de configuration, changement de contrat ou changement de chemin dans l'en-tête `file:`. - **DOC-HEAD-003** — Une transformation purement mécanique par un formatter officiel du projet, telle que `cargo fmt`, ne déclenche pas à elle seule d'incrément de version. - **DOC-HEAD-004** — Si un formatter est exécuté après une modification réelle du fichier, l'incrément reste requis à cause de la modification réelle. - **DOC-HEAD-005** — Un nouveau fichier versionné commence normalement à `version: 1`.