diff --git a/CHANGELOG.fr.md b/CHANGELOG.fr.md index 18bed67..0b7f969 100644 --- a/CHANGELOG.fr.md +++ b/CHANGELOG.fr.md @@ -10,6 +10,16 @@ publie par un tag, qui produit une archive signée (voir [RELEASING.fr.md](./RELEASING.fr.md)) ; l'unité qui compte reste le lab, et pour ce catalogue, la version du fil rouge. +## [Non publié] + +### Modifié + +- Le README renvoie à la documentation du moteur au lieu de la recopier + (dsoxlab#201) : les sections qui décrivaient le contrat de `dsoxlab` et la + vie d'un lab pointent sur la documentation de dsoxlab, qui reste juste quand + le moteur change. L'« Anatomie d'un lab » du CONTRIBUTING renvoie à la même + documentation pour le contrat de chaque fichier. + ## [0.2.3] - 2026-10-23 ### Ajouté diff --git a/CHANGELOG.md b/CHANGELOG.md index 4a76288..e093918 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,16 @@ published by a tag, which produces a signed archive (see [RELEASING.md](./RELEASING.md)); the unit that matters remains the lab, and for this catalog, the version of the common thread. +## [Unreleased] + +### Changed + +- The README links to the engine documentation instead of copying it + (dsoxlab#201): the sections that described the `dsoxlab` contract and the + life of a lab now point to the dsoxlab docs, which stay true when the engine + changes. The CONTRIBUTING "Anatomy of a lab" points to the same docs for the + contract of each file. + ## [0.2.3] - 2026-10-23 ### Added diff --git a/CONTRIBUTING.fr.md b/CONTRIBUTING.fr.md index 1fa9e42..6a1f821 100644 --- a/CONTRIBUTING.fr.md +++ b/CONTRIBUTING.fr.md @@ -68,7 +68,7 @@ laissent aucune trace dans ce qu'act produit. ```text labs/capstone// ├── lab.yaml # le contrat (id, level, runtime, fixtures, validation…) -├── lab.fr.yaml # surcharge FR du title/description UNIQUEMENT +├── lab.fr.yaml # surcharge FR du title, de la description et des libellés de critères UNIQUEMENT ├── README.md / README.fr.md # la leçon ├── scenario.md / scenario.fr.md # la situation, l'état à atteindre, la pratique SSDF visée ├── fixtures/ # notes-api tel que la version précédente l'a laissé @@ -79,6 +79,11 @@ labs/capstone// solution/capstone// # solution de référence, chiffrée par ansible-vault ``` +Cet arbre montre les conventions de ce catalogue. Ce que chaque fichier porte +pour le moteur, et les champs qu'accepte `lab.yaml`, sont documentés dans +dsoxlab : [guide de l'auteur](https://github.com/stephrobert/dsoxlab/blob/main/docs/catalog-author.fr.md) +et [contrat](https://github.com/stephrobert/dsoxlab/blob/main/docs/contract-v1.fr.md). + Il n'y a ici ni `setup.yaml` ni `cleanup.yaml` : `runtime.fixtures` déclare ce qui est copié, en préservant les sous-répertoires, et `dsoxlab clean` retire le répertoire de travail. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 29af6c9..47598b4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -67,7 +67,7 @@ action by SHA) are in the text and leave no trace in what act produces. ```text labs/capstone// ├── lab.yaml # the contract (id, level, runtime, fixtures, validation…) -├── lab.fr.yaml # FR override of title/description ONLY +├── lab.fr.yaml # FR override of title, description and criteria labels ONLY ├── README.md / README.fr.md # the lesson ├── scenario.md / scenario.fr.md # the situation, the target state, the SSDF practice targeted ├── fixtures/ # notes-api as the previous version left it @@ -78,6 +78,11 @@ labs/capstone// solution/capstone// # reference solution, encrypted with ansible-vault ``` +This tree shows this catalog's conventions. What each file holds for the +engine, and which fields `lab.yaml` accepts, is documented in dsoxlab: +[catalog author guide](https://github.com/stephrobert/dsoxlab/blob/main/docs/catalog-author.md) +and [contract](https://github.com/stephrobert/dsoxlab/blob/main/docs/contract-v1.md). + There is no `setup.yaml` and no `cleanup.yaml` here: `runtime.fixtures` declares what is copied, preserving subdirectories, and `dsoxlab clean` removes the working directory. diff --git a/README.fr.md b/README.fr.md index 6517f85..8edeebc 100644 --- a/README.fr.md +++ b/README.fr.md @@ -98,34 +98,23 @@ formulaire arrive prérempli par `dsoxlab support --issue`. ## Comment ça marche -### Le contrat déclaratif, à deux niveaux - -Le catalogue est décrit par des données, pas par du code, ce qui laisse le -moteur `dsoxlab` agnostique du domaine : - -- **`meta.yml`**, à la racine, déclare l'identité du dépôt et l'**ordre** des - versions, qui est celui du jeu : il ne se réordonne pas ; -- **`lab.yaml`**, par lab, déclare ses `skills`, son `level`, son `runtime` - (type, fixtures), ses `distros`, son `doc_url` et un bloc `validation`. Un - `lab.fr.yaml` surcharge le `title` et la `description` en français, et rien - d'autre. - -`dsoxlab validate-structure` contrôle tout le contrat, et -`tests/test_schemas_dsoxlab.py` confronte chaque `lab.yaml` au schéma publié par -dsoxlab. - -### Le cycle de vie d'un lab - -```bash -dsoxlab list-labs # parcourir le catalogue -dsoxlab show # métadonnées et état d'un lab -dsoxlab run # poser l'état de départ -dsoxlab challenge # lire la mission, sans pas-à-pas -dsoxlab hint # révéler un indice (déduit du score) -dsoxlab check # lancer les tests, calculer et enregistrer le score -dsoxlab clean # retirer le répertoire de travail -dsoxlab progress # avancement par section, score moyen -``` +### Le moteur, documenté là où il vit + +Ce catalogue se joue avec `dsoxlab`, qui documente lui-même son contrat et ses +commandes. Ce README ne les répète pas, pour ne pas dériver quand le moteur +change (issue dsoxlab #201) : + +- le contrat : `meta.yml`, `lab.yaml`, `lab..yaml`, les runtimes et + leurs champs : [contrat](https://github.com/stephrobert/dsoxlab/blob/main/docs/contract-v1.fr.md) ; +- les commandes et la vie d'un lab, de `run` à `check` : + [commandes](https://github.com/stephrobert/dsoxlab/blob/main/docs/commands.fr.md) et [jouer un lab](https://github.com/stephrobert/dsoxlab/blob/main/docs/learner.fr.md) ; +- écrire un lab, et ce que contrôle `validate-structure` : + [guide de l'auteur](https://github.com/stephrobert/dsoxlab/blob/main/docs/catalog-author.fr.md). + +Ce qui est propre à ce catalogue : [`meta.yml`](./meta.yml) porte l'ordre des +versions, qui est celui du jeu, et il ne se réordonne pas. +[`tests/test_schemas_dsoxlab.py`](./tests/test_schemas_dsoxlab.py) confronte +chaque `lab.yaml` au schéma publié par dsoxlab. ### Les runtimes diff --git a/README.md b/README.md index bc3f6a2..246959c 100644 --- a/README.md +++ b/README.md @@ -99,35 +99,23 @@ pre-filled by `dsoxlab support --issue`. ## How it works -### The declarative contract (two levels) - -The catalog is described by data, not code, which keeps the `dsoxlab` engine -domain-agnostic: - -- **`meta.yml`**, at the root, declares the repository's identity and the - **order** of the versions, which is the order of play: it is never - reordered; -- **`lab.yaml`**, per lab, declares its `skills`, its `level`, its `runtime` - (type, fixtures), its `distros`, its `doc_url` and a `validation` block. A - `lab.fr.yaml` overrides the `title` and the `description` in French, and - nothing else. - -`dsoxlab validate-structure` checks the whole contract, and -`tests/test_schemas_dsoxlab.py` checks each `lab.yaml` against the schema -published by dsoxlab. - -### The lab lifecycle - -```bash -dsoxlab list-labs # browse the catalog -dsoxlab show # a lab's metadata and state -dsoxlab run # set up the starting state -dsoxlab challenge # read the mission, no step-by-step -dsoxlab hint # reveal a hint (deducted from the score) -dsoxlab check # run the tests, compute and record the score -dsoxlab clean # remove the working directory -dsoxlab progress # progress per section, average score -``` +### The engine, documented where it lives + +This catalog is played by `dsoxlab`, which documents its own contract and +commands. This README does not repeat them, so that it cannot drift when the +engine changes (dsoxlab issue #201): + +- the contract: `meta.yml`, `lab.yaml`, `lab..yaml`, the runtimes and + their fields: [contract](https://github.com/stephrobert/dsoxlab/blob/main/docs/contract-v1.md); +- the commands and the life of a lab, from `run` to `check`: + [commands](https://github.com/stephrobert/dsoxlab/blob/main/docs/commands.md) and [playing a lab](https://github.com/stephrobert/dsoxlab/blob/main/docs/learner.md); +- writing a lab, and what `validate-structure` checks: + [catalog author guide](https://github.com/stephrobert/dsoxlab/blob/main/docs/catalog-author.md). + +What is specific to this catalog: [`meta.yml`](./meta.yml) carries the order +of the versions, which is the order of play, and it is never reordered. +[`tests/test_schemas_dsoxlab.py`](./tests/test_schemas_dsoxlab.py) checks +each `lab.yaml` against the schema published by dsoxlab. ### Runtimes