From 0156e1e7550a7bbbcfe01acfffecb6f93db9bee4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?St=C3=A9phane=20ROBERT?= Date: Sat, 14 Nov 2026 12:59:16 +0100 Subject: [PATCH 1/2] =?UTF-8?q?docs(moteur):=20renvoyer=20=C3=A0=20la=20do?= =?UTF-8?q?c=20du=20moteur=20au=20lieu=20de=20la=20recopier=20(dsoxlab#201?= =?UTF-8?q?)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Le README recopiait le contrat déclaratif et le cycle de vie d'un lab, qui décrivent dsoxlab et dérivent à chaque version du moteur. Ces sous-sections laissent la place au texte du squelette de `dsoxlab new catalog` : des liens vers contract-v1, commands, learner et catalog-author. Ce qui est propre au catalogue reste. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.fr.md | 11 +++++++++++ CHANGELOG.md | 10 ++++++++++ README.fr.md | 41 ++++++++++++----------------------------- README.md | 40 ++++++++++++---------------------------- 4 files changed, 45 insertions(+), 57 deletions(-) diff --git a/CHANGELOG.fr.md b/CHANGELOG.fr.md index 3c363c6..1e0b734 100644 --- a/CHANGELOG.fr.md +++ b/CHANGELOG.fr.md @@ -9,6 +9,17 @@ Ce dépôt est un **catalogue de contenu**, pas une bibliothèque : il n'est pas versionné et ne publie aucune release. Les entrées ci-dessous datent les modifications du catalogue, et l'unité qui compte est le lab. +## [Non publié] + +### Modifié + +- **Le README ne recopie plus la documentation du moteur, il y renvoie** + (issue dsoxlab #201). Les sous-sections « contrat déclaratif » et « cycle de + vie d'un lab » décrivaient `dsoxlab` lui-même, et une telle copie dérive à + chaque version du moteur. Elles laissent la place à des liens vers le + contrat, les commandes et le guide de l'auteur de dsoxlab. Ce qui est propre + au catalogue reste. + ## [0.2.2] - 2026-10-23 ### Ajouté diff --git a/CHANGELOG.md b/CHANGELOG.md index 96543fd..768e590 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,16 @@ This repository is a **content catalog**, not a library: it is not versioned and publishes no releases. The entries below date changes to the catalog, and the unit that matters is the lab. +## [Unreleased] + +### Changed + +- **The README no longer copies the engine's documentation, it links to it** + (dsoxlab issue #201). The "declarative contract" and "lab lifecycle" + subsections described `dsoxlab` itself, and such a copy drifts with every + engine release. They give way to links to the contract, the commands and the + catalog author guide of dsoxlab. What belongs to this catalog stays. + ## [0.2.2] - 2026-10-23 ### Added diff --git a/README.fr.md b/README.fr.md index f37ffd9..e4af2bf 100644 --- a/README.fr.md +++ b/README.fr.md @@ -90,35 +90,18 @@ doctor` dit ce dont ce dépôt a besoin, et ce dont il n'a pas besoin. ## Comment ça marche -### Le contrat déclaratif, à deux niveaux - -Le catalogue est décrit par des données, pas par du code, et c'est ce qui garde -le moteur `dsoxlab` indépendant du domaine : - -- **`meta.yml`** à la racine déclare l'identité du dépôt et l'**ordre** des - sections affichées par `list-labs` ; -- **`lab.yaml`** par lab déclare ses `skills`, son `level`, son `runtime` - (type, fixtures, services), ses `distros`, son `doc_url` et un bloc - `validation`. Un `lab.fr.yaml` surcharge `title` et `description` en - français, et rien d'autre. - -`dsoxlab validate-structure` contrôle tout le contrat : `meta.yml` bien formé, -chaque lab référencé présent avec un `lab.yaml` valide, chaque fichier de test -et de fixture déclaré réellement là, et chaque lien relatif d'un README qui -mène quelque part. - -### 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). ### Les runtimes diff --git a/README.md b/README.md index 9265c7e..a4a537e 100644 --- a/README.md +++ b/README.md @@ -89,34 +89,18 @@ and what it does not. ## How it works -### The declarative contract (two levels) - -The catalog is described by data, not code, which is what keeps the `dsoxlab` -engine domain-agnostic: - -- **`meta.yml`** at the root declares the repository identity and the **order** - of the sections shown by `list-labs`; -- **`lab.yaml`** per lab declares its `skills`, `level`, `runtime` (type, - fixtures, services), `distros`, `doc_url` and a `validation` block. A - `lab.fr.yaml` overrides `title` and `description` in French, and nothing else. - -`dsoxlab validate-structure` checks the whole contract: `meta.yml` is well -formed, every referenced lab exists with a valid `lab.yaml`, every declared test -and fixture file is really there, and every relative link in a README leads -somewhere. - -### The lab lifecycle - -```bash -dsoxlab list-labs # browse the catalog -dsoxlab show # metadata and status of one lab -dsoxlab run # set 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 work directory -dsoxlab progress # per-section progress, 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). ### Runtimes From d40c7a680b5605c1d6f3b40dba078d8130834e3d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?St=C3=A9phane=20ROBERT?= Date: Sat, 14 Nov 2026 14:09:45 +0100 Subject: [PATCH 2/2] =?UTF-8?q?docs(contribuer):=20lab.fr.yaml=20surcharge?= =?UTF-8?q?=20aussi=20les=20libell=C3=A9s=20de=20crit=C3=A8res?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Le contrat de dsoxlab le dit désormais (dsoxlab#374) : un lab..yaml surcharge title, description et le label de chaque critère. Co-Authored-By: Claude Opus 5.5 --- CONTRIBUTING.fr.md | 2 +- CONTRIBUTING.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.fr.md b/CONTRIBUTING.fr.md index bc78d00..481e9c6 100644 --- a/CONTRIBUTING.fr.md +++ b/CONTRIBUTING.fr.md @@ -71,7 +71,7 @@ tirés au hasard, et la graine s'affiche en cas d'échec. ```text labs// ├── lab.yaml # le contrat (id, niveau, runtime, fixtures, validation…) -├── lab.fr.yaml # surcharge française de title/description SEULEMENT +├── lab.fr.yaml # surcharge française du title, de la description et des libellés de critères SEULEMENT ├── README.md / README.fr.md # la présentation ├── scenario.md / scenario.fr.md # la situation, l'état visé, la preuve ├── fixtures/ # le point de départ, copié dans challenge/work diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 930e3c8..b59cbaf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -69,7 +69,7 @@ and the seed is printed on failure. ```text labs// ├── lab.yaml # the contract (id, level, runtime, fixtures, validation…) -├── lab.fr.yaml # French override of title/description ONLY +├── lab.fr.yaml # French override of title, description and criteria labels ONLY ├── README.md / README.fr.md # the presentation ├── scenario.md / scenario.fr.md # the situation, the target state, the proof ├── fixtures/ # the starting material, copied into challenge/work