Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions CHANGELOG.fr.md
Original file line number Diff line number Diff line change
Expand Up @@ -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é
Expand Down
10 changes: 10 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion CONTRIBUTING.fr.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ tirés au hasard, et la graine s'affiche en cas d'échec.
```text
labs/<lab>/
├── 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
Expand Down
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@ and the seed is printed on failure.
```text
labs/<lab>/
├── 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
Expand Down
41 changes: 12 additions & 29 deletions README.fr.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <id> # métadonnées et état d'un lab
dsoxlab run <id> # poser l'état de départ
dsoxlab challenge <id> # lire la mission, sans pas-à-pas
dsoxlab hint <id> # révéler un indice (déduit du score)
dsoxlab check <id> # lancer les tests, calculer et enregistrer le score
dsoxlab clean <id> # 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.<langue>.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

Expand Down
40 changes: 12 additions & 28 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <id> # metadata and status of one lab
dsoxlab run <id> # set the starting state
dsoxlab challenge <id> # read the mission, no step-by-step
dsoxlab hint <id> # reveal a hint (deducted from the score)
dsoxlab check <id> # run the tests, compute and record the score
dsoxlab clean <id> # 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.<lang>.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

Expand Down