khadhroony-solana-project/docs/rules/RULES_DOCUMENTATION.md

Règles de documentation

Portée

Les règles DOC-* s'appliquent aux documents Markdown internes et à leur organisation.

Principes

• DOC-ROOT-001 — README.md à la racine décrit KSP, sa finalité, ses principes structurants et les points d'entrée du dépôt ; il ne sert ni de changelog ni de plan détaillé de version.
• DOC-ROOT-002 — Le point d'entrée d'un répertoire documentaire utilisant une priorité explicite se nomme 000-README.md. Le préfixe 000- garantit qu'il reste en première position dans les listings et arbres de fichiers lorsque le volume documentaire devient important.
• DOC-ROOT-003 — Dans un répertoire documentaire où un ordre de lecture, de priorité ou d'affichage est utile, les autres documents prioritaires peuvent être préfixés 001-, 002-, etc. Le préfixe numérique n'est pas appliqué mécaniquement à tous les fichiers.
• DOC-ROOT-004 — La convention 000-, 001-, 002-, etc. ne s'applique pas aux fichiers situés à la racine du dépôt. README.md, RULES.md, ROADMAP.md, CHANGELOG.md et les autres fichiers racine conservent leur nom canonique sans préfixe numérique.
• DOC-ROOT-005 — RULES.md est le seul index normatif à la racine et renvoie vers les règles détaillées sous docs/rules/.
• DOC-ROOT-006 — KSP utilisera au plus un CHANGELOG.md général à la racine ; aucun changelog spécifique par crate ou module n'est créé par défaut.
• DOC-ROOT-007 — ROADMAP.md décrit les objectifs et grandes étapes globales par phase/version. Chaque bloc peut comporter un Status optionnel et utilise la légende [ ] prévu, [/] en cours, [X] réalisé et validé, [C] annulé et [R] reporté.
• DOC-ROOT-008 — CHANGELOG.md contient les releases stables dans un ordre chronologique décroissant. Chaque release est résumée par un ou plusieurs paragraphes ; le changelog général ne recopie pas le détail des deltas.

Deltas et documents durables

• DOC-DELTA-001 — Les fichiers deltas/<X.Y.Z>/<delta-name>.md sont des journaux de livraison versionnés et commités ; ils ne sont pas placés sous docs/.
• DOC-DELTA-002 — Aucun second système de fichiers de version n'est créé sous docs/.
• DOC-DELTA-003 — Les décisions devenues durables sont reportées dans les documents normatifs, architecturaux ou de référence appropriés ; le delta reste une trace historique de la livraison.
• DOC-DELTA-004 — Le changelog général, lorsqu'il sera défini et introduit, synthétisera les changements significatifs sans dupliquer chaque détail des deltas.

Idées à explorer

• DOC-IDEAS-001 — docs/IDEAS.md conserve les idées, pistes, alternatives et questions qui doivent rester visibles sans constituer encore une décision ou un engagement de développement.
• DOC-IDEAS-002 — Une idée peut utiliser les statuts À explorer, En exploration, Retenue, Rejetée, Transférée au roadmap ou Transférée vers une décision/règle.
• DOC-IDEAS-003 — Lorsqu'une idée devient un engagement, elle est transférée vers le roadmap ou un plan ; lorsqu'elle devient une décision durable, elle est reportée dans le document normatif ou architectural approprié. IDEAS.md conserve une trace concise de son issue.
• DOC-IDEAS-004 — IDEAS.md ne doit pas devenir un second roadmap ni une liste de tâches de développement promises.

Format des tableaux Markdown

• DOC-TABLE-001 — Un tableau Markdown KSP utilise | uniquement comme séparateur structurel de colonnes. Un caractère | littéral, y compris sous forme échappée \|, est interdit dans le contenu d’une cellule ; reformuler le contenu, utiliser /, et, une liste ou un bloc de code hors tableau.
• DOC-TABLE-002 — Toutes les lignes d’un même tableau ont leurs séparateurs verticaux aux mêmes positions. La largeur de chaque colonne est déterminée par le contenu le plus large de cette colonne, en comptant l’en-tête et les lignes de données.
• DOC-TABLE-003 — Chaque cellule de contenu commence par exactement un espace après le séparateur | gauche. Dans la cellule qui porte le contenu le plus large d’une colonne, il existe aussi exactement un espace entre le contenu et le séparateur | droit. Les cellules plus courtes conservent l’unique espace gauche et reçoivent uniquement le padding droit nécessaire pour aligner les séparateurs verticaux.
• DOC-TABLE-004 — La ligne séparatrice en tirets occupe exactement la même largeur que chaque colonne ; les marqueurs : de l’alignement Markdown restent autorisés lorsqu’ils sont intentionnels. Le résultat attendu est équivalent au reformatage de tableau produit par RustRover, mais la règle structurelle KSP prime sur l’éditeur utilisé.
• DOC-TABLE-005 — Lorsqu’une modification touche une ligne d’un tableau, le tableau entier est réaligné avant livraison. python3 scripts/audit_markdown_tables.py <fichiers-markdown-modifiés> est le canari mécanique recommandé pour les fichiers concernés ; les blocs de code fenced ne sont pas interprétés comme des tableaux.
• DOC-TABLE-006 — L’immuabilité des deltas déjà publiés prime sur un reformatage rétrospectif : un ancien fichier deltas/ n’est jamais réécrit uniquement pour satisfaire une règle de présentation introduite ultérieurement. Tout nouveau delta et tout autre tableau modifiable créé ou touché doivent en revanche respecter immédiatement DOC-TABLE-001 à DOC-TABLE-005.

Espacement vertical Markdown

• DOC-BLANK-001 — Hors bloc de code fenced, un document Markdown KSP ne contient jamais plus d’une ligne vide consécutive. Une ligne composée uniquement d’espaces ou de tabulations est considérée comme vide.
• DOC-BLANK-002 — python3 scripts/audit_markdown_tables.py <fichiers-ou-répertoires> contrôle aussi les lignes vides multiples. Lors d’un parcours récursif, les répertoires générés ou tiers tels que node_modules, dist, target, .git, .idea, .venv et __pycache__ sont exclus afin que le résultat porte uniquement sur les Markdown KSP-owned. Les blocs de code fenced conservent librement leur espacement interne.
• DOC-BLANK-003 — Les deltas déjà publiés restent immuables et ne sont jamais réécrits uniquement pour satisfaire DOC-BLANK-001. Les audits de release portent sur le répertoire de delta actif et sur les autres Markdown modifiables ; un audit historique explicite peut donc signaler des écarts hérités sans autoriser leur correction rétroactive.

Contenu et exactitude

• DOC-CONTENT-001 — Une documentation décrit l'état réellement décidé ou validé et distingue explicitement les hypothèses, propositions, TODO et questions ouvertes.
• DOC-CONTENT-002 — Une validation non exécutée est identifiée comme telle.
• DOC-CONTENT-003 — Une source historique est synthétisée et réévaluée ; elle n'est pas copiée mécaniquement comme documentation KSP active.
• DOC-CONTENT-004 — Les exemples de chemins et noms suivent la nomenclature KSP active au moment de l'écriture.

Documents de crates

• DOC-CRATE-001 — Il est préférable qu'une crate dispose de README.md, TODO.md et surtout USAGE.md, mais leur présence n'est pas imposée mécaniquement lorsque le fichier n'apporte encore aucune information utile.
• DOC-CRATE-002 — README.md décrit la responsabilité, le périmètre, les frontières et les principaux points d'entrée d'une crate.
• DOC-CRATE-003 — TODO.md conserve les tâches, lacunes et vérifications propres à la crate afin d'éviter les oublis ; il ne remplace pas la planification globale ou les deltas.
• DOC-CRATE-004 — USAGE.md documente l'utilisation concrète de la crate, ses préconditions, ses principaux contrats et des exemples pertinents ; il est particulièrement recommandé dès qu'une crate possède une API consommable.
• DOC-CRATE-005 — Aucun CHANGELOG.md de crate n'est créé par défaut ; la traçabilité détaillée est assurée par deltas/ et, lorsqu'il sera défini, par le changelog général.