From f064e453adfb09682e054072b62146f45aacd106 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?St=C3=A9phane=20ROBERT?= Date: Sat, 14 Nov 2026 12:48:08 +0100 Subject: [PATCH] =?UTF-8?q?docs(moteur):=20renvoyer=20=C3=A0=20la=20doc=20?= =?UTF-8?q?du=20moteur=20au=20lieu=20de=20la=20recopier=20(dsoxlab#201)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Les sections du README qui recopiaient le contrat de dsoxlab et le cycle de vie d'un lab sont remplacées par la section du squelette de `dsoxlab new catalog` (main 2663b6b), qui renvoie à la documentation du moteur. Ce qui est propre au catalogue reste : les sections-modules, les runtimes et ce que act ne joue pas, le modèle de validation. L'« Anatomie d'un lab » du CONTRIBUTING garde ses conventions et renvoie au guide de l'auteur et au contrat de dsoxlab. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.fr.md | 10 +++++++++ CHANGELOG.md | 10 +++++++++ CONTRIBUTING.fr.md | 5 +++++ CONTRIBUTING.md | 5 +++++ README.fr.md | 56 ++++++++++++++++------------------------------ README.md | 54 +++++++++++++++----------------------------- 6 files changed, 67 insertions(+), 73 deletions(-) diff --git a/CHANGELOG.fr.md b/CHANGELOG.fr.md index 7ee180c..12ef67c 100644 --- a/CHANGELOG.fr.md +++ b/CHANGELOG.fr.md @@ -21,6 +21,16 @@ ne recule pas, et 0.2.0 sous v1.2.0 aurait menti sur l'ordre des choses. --- +## [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 8081593..66da09c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,6 +20,16 @@ backwards, and 0.2.0 under v1.2.0 would have lied about the order of things. --- +## [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 957a561..8001793 100644 --- a/CONTRIBUTING.fr.md +++ b/CONTRIBUTING.fr.md @@ -101,6 +101,11 @@ labs/-/ └── tests/test_functional.py # la preuve, lue par pytest (nom imposé) ``` +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). + `dsoxlab new lab --runtime shell` crée le squelette. L'identifiant suit `-`, en minuscules et en français : `fondations-premier-workflow`. `section` et `level` reprennent l'identifiant diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 184c719..adfc1c0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -99,6 +99,11 @@ labs/-/ └── tests/test_functional.py # the proof, read by pytest (fixed name) ``` +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). + `dsoxlab new lab --runtime shell` creates the skeleton. The identifier follows `-`, lowercase and in French, the course language: `fondations-premier-workflow`. `section` and `level` repeat the identifier of diff --git a/README.fr.md b/README.fr.md index ec203fd..a92e47f 100644 --- a/README.fr.md +++ b/README.fr.md @@ -127,43 +127,25 @@ travail. ## Comment ça marche -### Le contrat déclaratif (deux niveaux) - -Le catalogue est décrit par des données, pas par du code : le moteur `dsoxlab` -reste agnostique du domaine et lit deux niveaux de fichiers. - -- **`meta.yml`** à la racine déclare l'identité du dépôt et l'**ordre** des - sections affiché par `list-labs`. Chaque section est un module du parcours du - blog. Il n'y a pas de bloc `infra` : aucune machine à provisionner. -- **`lab.yaml`** par lab (sous `labs/-/`) déclare ses `skills`, - son `level` (le module du parcours), son `runtime` et ses `fixtures`, son - `doc_url` (la leçon jumelée) et un bloc `validation`. Un `lab.fr.yaml` - optionnel surcharge le `title` et la `description` en français. - -`dsoxlab validate-structure` vérifie tout le contrat : le `meta.yml` est -conforme, chaque lab référencé existe avec un `lab.yaml` valide, et chaque -fixture ou fichier de test référencé est présent. - -### Le cycle de vie d'un lab - -L'apprenant pilote tout via la CLI ; un parcours type : - -```bash -dsoxlab doctor # vérifier l'environnement (Python, pytest, runtimes, labs) -dsoxlab list-labs # parcourir le catalogue -dsoxlab show # métadonnées et statut d'un lab -dsoxlab run # préparer l'espace de travail -dsoxlab course # lire le cours guidé (optionnel) -dsoxlab challenge # lire la mission (sans pas-à-pas) -dsoxlab hint # révéler un indice (déduit du score) -dsoxlab check # jouer les workflows, calculer et noter -dsoxlab submit # soumission finale, ferme la session -dsoxlab progress # progression par bloc, score moyen -``` - -C'est `run` qui monte l'environnement : il crée le `workdir` du lab et copie -les fixtures déclarées. Tout se passe ensuite sur ton poste, dans ce -répertoire, comme dans un vrai dépôt. +### 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 : chaque section du [`meta.yml`](./meta.yml) +est un module du parcours du blog, et il n'y a pas de bloc `infra` : aucune +machine à provisionner. Chaque lab vit sous `labs/-/` ; son +`level` est le module du parcours et son `doc_url` la leçon jumelée. `run` +prépare le répertoire de travail du lab, et tout se passe ensuite sur ton +poste, dans ce répertoire, comme dans un vrai dépôt. ### Les runtimes diff --git a/README.md b/README.md index c66e346..160f930 100644 --- a/README.md +++ b/README.md @@ -126,42 +126,24 @@ work. ## How it works -### The declarative contract (two levels) - -The catalogue is described by data, not by code: the `dsoxlab` engine stays -domain-agnostic and reads two levels of files. - -- **`meta.yml`** at the root declares the repository identity and the - **order** of the sections shown by `list-labs`. Each section is a module of - the blog course. There is no `infra` block: no machine to provision. -- **`lab.yaml`** per lab (under `labs/-/`) declares its - `skills`, its `level` (the course module), its `runtime` and `fixtures`, its - `doc_url` (the paired lesson) and a `validation` block. An optional - `lab.fr.yaml` overrides the `title` and `description` in French. - -`dsoxlab validate-structure` checks the whole contract: `meta.yml` is -compliant, every referenced lab exists with a valid `lab.yaml`, and every -referenced fixture or test file is present. - -### The lab lifecycle - -The learner drives everything through the CLI; a typical path: - -```bash -dsoxlab doctor # check the environment (Python, pytest, runtimes, labs) -dsoxlab list-labs # browse the catalogue -dsoxlab show # a lab's metadata and status -dsoxlab run # prepare the workspace -dsoxlab course # read the guided course (optional) -dsoxlab challenge # read the mission (no step-by-step) -dsoxlab hint # reveal a hint (deducted from the score) -dsoxlab check # run the workflows, compute and score -dsoxlab submit # final submission, closes the session -dsoxlab progress # progress per block, average score -``` - -`run` is what sets up the environment: it creates the lab's `workdir` and -copies the declared fixtures. Everything then happens on your machine, in that +### 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: each section of [`meta.yml`](./meta.yml) is +a module of the blog course, and there is no `infra` block, so no machine to +provision. Each lab lives under `labs/-/`; its `level` is the +course module and its `doc_url` the paired lesson. `run` prepares the lab's +working directory, and everything then happens on your machine, in that directory, as in a real repository. ### Runtimes