|
|
|
|
@@ -1,8 +1,10 @@
|
|
|
|
|
<!-- file: docs/rules/RULES_DOCUMENTATION.md -->
|
|
|
|
|
<!-- version: 2 -->
|
|
|
|
|
<!-- version: 3 -->
|
|
|
|
|
|
|
|
|
|
# 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/`.
|
|
|
|
|
@@ -11,11 +13,72 @@
|
|
|
|
|
- **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.
|
|
|
|
|
- **DOC-009** — Un fichier sous `deltas/<X.Y.Z>/` décrit exactement la tranche livrée, son état de base et ses commandes de validation ; il est immuable après livraison.
|
|
|
|
|
- **DOC-010** — L'historique transitoire validé réside sous `history/<X.Y.Z>/` avec un fichier immuable par jalon accepté.
|
|
|
|
|
- **DOC-011** — 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-012** — 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-013** — `CHANGELOG.md` reste une synthèse destinée aux jalons significatifs et ne reproduit pas l'historique détaillé des `pre.*` et de leurs fixes.
|
|
|
|
|
- **DOC-014** — Après la structuration initiale de `0.1.0`, les `pre.*` et `.fix.*` ne modifient normalement pas `CHANGELOG.md`. Les entrées `alpha` et `beta` peuvent y apparaître uniquement lorsqu'elles correspondent à un jalon externe significatif ; `rc` et releases stables y sont les jalons privilégiés.
|
|
|
|
|
- **DOC-015** — `ROADMAP.md` n'est pas modifié mécaniquement à chaque delta ; il change uniquement lorsque le périmètre, l'ordre, les objectifs ou les jalons planifiés évoluent réellement.
|
|
|
|
|
- **DOC-016** — `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.
|
|
|
|
|
|
|
|
|
|
## 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.
|
|
|
|
|
|
|
|
|
|
## 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** — Les marqueurs ROADMAP canoniques sont exclusivement `( )`, `(x)`, `(d)` et `(c)`. La syntaxe Markdown task-list `[ ]` / `[x]` n'est pas utilisée.
|
|
|
|
|
- **DOC-RMAP-003** — `( )` signifie `planned`, `(x)` signifie `completed`, `(d)` signifie `deferred` et `(c)` signifie `cancelled`.
|
|
|
|
|
- **DOC-RMAP-004** — Les marqueurs sont des statuts de lignes de scope, pas nécessairement un statut global de version.
|
|
|
|
|
- **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.
|
|
|
|
|
|
