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-009 — Les cellules d'un tableau Markdown sont remplies avec des espaces afin que chaque colonne ait une largeur brute constante sur toutes les lignes de contenu.
• DOC-010 — La ligne séparatrice ne contient aucun espace de padding : chaque cellule séparatrice remplit exactement la largeur brute de sa colonne avec des tirets, comme dans |-----------|----------------|.
• DOC-011 — Les marqueurs Markdown d'alignement : ne sont utilisés que lorsqu'un alignement sémantique différent de l'alignement par défaut est nécessaire ; ils remplacent alors des tirets sans modifier la largeur brute exacte de la cellule séparatrice.
• DOC-012 — Les tableaux d'un même document conservent une convention cohérente et doivent passer scripts/audit_markdown_tables.py avant livraison.
• 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.
• DOC-CAT-009 — docs/plans/ contient les plans vivants des versions concrètes. Un plan détaille le scope, les décisions, les validations et surtout le découpage prévisionnel souple des prereleases ; il ne remplace ni ROADMAP.md ni les deltas.

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.

Documentation des crates, applications et packages

• DOC-CRATE-001 — Toute nouvelle crate, application ou package frontend évalue explicitement pendant son cadrage puis sa consolidation finale si un README.md ou un USAGE.md apporte une information durable utile ; ces fichiers ne sont jamais créés uniquement pour satisfaire une cérémonie.
• DOC-CRATE-002 — Un README.md local décrit la responsabilité, les frontières, les dépendances structurantes et les principaux points d'entrée lorsqu'un composant devient durable ou réutilisable et que ces informations ne sont pas suffisamment couvertes par une documentation centrale.
• DOC-CRATE-003 — Un USAGE.md est ajouté lorsqu'une API, un binaire, une application ou un package possède un workflow de consommation/opérateur, des préconditions, des commandes, de la configuration ou des exemples suffisamment non triviaux pour mériter un guide stable.
• DOC-CRATE-004 — Un adapter ou POC très petit peut rester documenté uniquement par les documents d'architecture/développement existants lorsque cela couvre réellement son contrat ; l'absence de README.md/USAGE.md doit alors être un choix de valeur documentaire, pas un oubli.
• DOC-CRATE-005 — README.md et USAGE.md restent durables et ne contiennent pas de journal de release ; les changements de version appartiennent à CHANGELOG.md, deltas/ et history/.

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.