games/docs/rules/RULES_DOCUMENTATION.md

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-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 → <version> 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 <version> 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/<X.Y.Z>/ 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/<X.Y.Z>/ 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.