v0.0.2
This commit is contained in:
57
docs/rules/FILE_CONTRACTS.md
Normal file
57
docs/rules/FILE_CONTRACTS.md
Normal file
@@ -0,0 +1,57 @@
|
||||
<!-- file: docs/rules/FILE_CONTRACTS.md -->
|
||||
<!-- version: 6 -->
|
||||
|
||||
# Contrats des fichiers
|
||||
|
||||
## Portée
|
||||
|
||||
Les règles `FILE-*` définissent la responsabilité et le mode de modification des principales familles de fichiers KSP. Un nouveau type de fichier durable doit recevoir un contrat avant de devenir une convention répétée.
|
||||
|
||||
## Fichiers racine et configuration Cargo
|
||||
|
||||
| Fichier | Responsabilité | Règle de modification |
|
||||
|----------------------|-----------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| `.gitignore` | Exclure uniquement les artefacts non versionnés décidés par le projet. | Ajouter une exclusion lorsqu'un besoin réel apparaît ; éviter les exclusions spéculatives. |
|
||||
| `README.md` | Présenter KSP, sa finalité, son périmètre général, ses principes et les points d'entrée. | Mettre à jour lorsqu'une définition structurante du projet change ; ne pas y consigner l'historique des versions. |
|
||||
| `RULES.md` | Indexer les règles normatives. | Modifier uniquement lorsque la structure normative ou ses points d'entrée changent. |
|
||||
| `Cargo.toml` | Définir le workspace, sa version Cargo, les métadonnées héritées et les lints communs. | Modifier lors de toute prerelease/release non-fix, lors d'un correctif touchant le code/build/runtime/configuration/migrations, lorsqu'une crate entre/sort du workspace ou lorsqu'un contrat Cargo commun change. Un correctif purement documentaire ou de référence non consommée par le runtime ne force pas un changement de version Cargo. |
|
||||
| `.cargo/config.toml` | Définir les réglages Cargo propres au workspace qui ne relèvent pas du manifeste, notamment l'emplacement des artefacts de build. | Modifier lorsqu'un réglage Cargo commun change ; ne pas y placer de secret ni de configuration spécifique à une machine particulière. |
|
||||
| `rustfmt.toml` | Définir le formatage Rust commun. | Modifier comme changement normatif, avec justification dans le delta. |
|
||||
| `clippy.toml` | Définir les paramètres Clippy communs. | Modifier comme changement normatif, avec justification dans le delta. |
|
||||
| `ROADMAP.md` | Décrire les objectifs globaux et les grandes étapes prévues par phase/version, avec leur état synthétique. | Modifier lorsqu'un objectif, une grande étape, un report, une annulation ou un état global change ; ne pas y recopier le détail des prereleases prévu dans les plans de version. |
|
||||
| `CHANGELOG.md` | Résumer les releases stables dans un ordre chronologique décroissant, sous forme d'un ou plusieurs paragraphes par release. | Synchroniser lors de la phase documentaire finale ; ne pas dupliquer les deltas ni créer de changelog par crate/module. |
|
||||
|
||||
## Répertoire `docs/`
|
||||
|
||||
| Fichier/famille | Responsabilité | Règle de modification |
|
||||
|---------------------------------|----------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| `docs/000-README.md` | Indexer et expliquer la documentation tout en restant en tête des listings et arbres de fichiers. | Modifier lorsque l'organisation durable de `docs/` change ; `000-README.md` reste prioritaire lorsqu'un ordre numérique existe. |
|
||||
| `docs/rules/*.md` | Définir les règles normatives par portée. | Modifier uniquement pour une décision normative ; incrémenter la version du fichier à chaque enregistrement modifiant son contenu. |
|
||||
| `docs/IDEAS.md` | Conserver les idées, pistes, questions et alternatives à explorer qui ne sont pas encore des engagements du roadmap. | Ajouter une idée dès qu'elle mérite d'être conservée ; mettre à jour son statut lorsqu'elle est explorée, retenue, rejetée ou transférée vers un plan, le roadmap, une règle ou une décision. |
|
||||
| futurs documents d'architecture | Décrire l'architecture courante décidée. | Ne pas utiliser comme journal de livraison ; reporter les décisions depuis les deltas/plans. |
|
||||
| futurs documents de référence | Définir vocabulaire, identifiants et références canoniques. | Mettre à jour quand la référence canonique évolue. |
|
||||
| futurs plans | Organiser une phase ou version complexe. | Ils peuvent évoluer pendant la phase ; leur statut normatif doit être explicite. |
|
||||
| futures validations | Conserver des résultats réellement exécutés. | Ne jamais enregistrer une validation supposée comme réussie. |
|
||||
|
||||
## Répertoire `deltas/`
|
||||
|
||||
| Fichier | Responsabilité | Règle de modification |
|
||||
|----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| `deltas/<X.Y.Z>/<delta-name>.md` | Tracer une livraison précise, sa base, son contenu, ses suppressions, validations et questions ouvertes, regroupée sous la version cible `X.Y.Z`. | Créé avec la livraison ; une livraison déjà publiée n'est pas réécrite silencieusement. Les prereleases utilisent `pre.NNN`, leurs correctifs `pre.NNN-fix.NNN`, et les publications de release utilisent `rel.NNN`. |
|
||||
|
||||
## Rust
|
||||
|
||||
| Fichier/famille | Responsabilité | Règle de modification |
|
||||
|----------------------------|-----------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| `crates/<name>/Cargo.toml` | Définir un package Rust et ses dépendances/features propres. | Toute dépendance doit correspondre à un usage réel ; les contraintes de version inhabituelles sont documentées. |
|
||||
| `src/lib.rs` | Définir la façade d'une bibliothèque. | Les modules restent privés ; l'API est réexportée explicitement. |
|
||||
| `src/main.rs` | Définir le point d'entrée d'un exécutable Rust. | Ne doit pas devenir un conteneur de logique métier réutilisable. |
|
||||
| modules Rust | Porter une responsabilité cohérente. | Un module est séparé ou fusionné selon ses invariants et responsabilités, pas uniquement selon sa taille. |
|
||||
| `unit_tests/` | Porter les tests unitaires physiquement séparés du code de production, en miroir de `src/` autant que possible. | Les fichiers restent rattachés sous `#[cfg(test)]` au module testé afin de conserver l'accès au privé ; cette séparation est utilisée au maximum. |
|
||||
| `tests/` | Porter exclusivement les tests d'intégration Cargo de la crate. | Les tests consomment uniquement l'API publique ; les contrats publics pertinents y sont testés lorsque techniquement possible. |
|
||||
|
||||
## Fichiers générés
|
||||
|
||||
- **FILE-GEN-001** — Un fichier généré n'est jamais modifié manuellement lorsque sa source de vérité est un générateur.
|
||||
- **FILE-GEN-002** — Le choix de versionner ou ignorer une famille générée est décidé explicitement lorsqu'elle apparaît.
|
||||
- **FILE-GEN-003** — Les futurs artefacts Tauri `bindings/` et `gen/` ne sont pas encore une convention KSP en `0.0.2-pre.001-fix.001`.
|
||||
Reference in New Issue
Block a user