L'étude de cas est ce que vous êtes en train de lire

Pourquoi la plateforme est l’exemple

Tous les autres cours d’ici emploient un jeu de données. Celui-ci emploie le dépôt, pour une raison qui vaut d’être énoncée : une chaîne reproductible est une affirmation sur un artefact, et la seule démonstration convaincante est un artefact que vous pouvez vérifier.

Tout ce qui suit se vérifie depuis un clone.

Des données brutes produites, non collectées

pnpm datasets:generate
git status --short apps/data-analysis/public/datasets/files
# (nothing)

Vingt fichiers CSV, dix-sept scripts générateurs, et les régénérer tous ne change rien. Chaque générateur a une graine fixe — SEED = 20240622, dans le fichier — si bien que la sortie est une fonction du seul code.

C’est une propriété plus forte que « la chaîne se réexécute ». Cela signifie que réexécuter est une étape de vérification : si git status n’est pas vide après une régénération, ou bien le générateur a changé, ou bien le fichier commité a été édité à la main, et vous voulez savoir l’un comme l’autre.

Et les défauts sont délibérés. Chaque entrée de la liste knownIssues d’un jeu de données correspond à un bloc de son générateur — les quatre orthographes de Nord-Ouest, les onze erreurs d’unité, les deux élèves en double. Changez l’un et vous changez l’autre, ce qui est la même discipline que celle des figures produites depuis les données.

Une sortie commitée, pour une raison qui nomme sa condition

Le dépôt commite des choses qu’il pourrait reconstruire : CSV de données, PDF de cours, diaporamas, figures, carnets.

Parce que le déploiement tourne sur Cloudflare Pages sans TeX, sans Python et sans pandoc. La compilation copie des fichiers statiques, si bien que LaTeX n’est jamais sur le chemin critique du déploiement et qu’un contributeur sans la chaîne d’outils peut quand même livrer un changement de contenu.

C’est la règle générale de la leçon 1, appliquée. Commitez un artefact produit quand le reconstruire n’est pas à la portée de tous ceux qui en ont besoin. Non parce que reconstruire est lent — parce que reconstruire est indisponible.

Et cela fonctionne parce que la sortie est déterministe. SOURCE_DATE_EPOCH fixe l’horodatage de pdfTeX et celui de pandoc, si bien qu’un .pptx — une archive dont les dates d’entrée bougeraient sinon — se reconstruit à l’octet près. Sans cela, commiter la sortie produite donnerait un diff à chaque compilation et personne n’en relirait aucun.

Des vérifications à trois endroits, et la contrainte qui a décidé où

Où	Quoi	Pourquoi là
Schéma Zod	Types de champs, énumérations, champs requis	S’exécute sur une entrée, sans système de fichiers
astro build	Sept vérifications de niveau graphe	A besoin de toute la collection
pnpm test	Vérifications de système de fichiers	La compilation n’a pas node:fs

La compilation Astro pré-rend dans un worker Cloudflare sans node:fs, si bien qu’une vérification qui doit regarder un fichier sur le disque ne peut pas y vivre. dataset-files.test.ts vérifie que les lignes et octets déclarés correspondent aux fichiers ; course-pdfs.test.ts vérifie que chaque cours publié livre ses deux éditions PDF.

Placez la vérification là où elle peut s’exécuter. C’est une contrainte d’ingénierie réelle, et elle a produit un meilleur agencement que l’élégance ne l’aurait fait : les vérifications rapides sont dans le schéma, celles de graphe dans la compilation, et celles de système de fichiers dans une suite de tests qui passe en premier en intégration continue.

La vérification qu’un graphe de références ne peut pas exprimer

REFERENCE_RULES verifies that a declared slug resolves.
It cannot verify that an entry is pointed at.

Un cours pourrait donc être livré sans laboratoire ni exercice, et chaque barrière resterait verte. C’est pour cela qu’existe course-practice.test.ts — il compte à rebours depuis chaque cours publié vers la pratique qui doit le nommer.

Toute règle du type « chaque X a au moins un Y » exige un test de cette forme, et reconnaître lesquelles de vos contraintes sont de ce genre constitue l’essentiel de la conception d’une suite de vérifications.

Ce que le dépôt refuse de contenir

.refine((d) => d.dataQuality.synthetic === true, {
  message: "Only synthetic or fully de-identified datasets may be published.",
})

Un jeu de données non déclaré synthétique fait échouer la compilation. Ce public modélise des données de bénéficiaires, de protection, de VBG et cliniques, et « aucun enregistrement ne remonte à une personne réelle » devient une propriété du dépôt plutôt qu’une promesse dans une note.

Cela va de pair avec produire les données plutôt que les collecter. La garantie est structurelle aux deux bouts : le générateur ne peut pas produire une personne réelle, et le schéma n’acceptera pas une affirmation contraire.

La reproductibilité au niveau du langage

{ "packageManager": "pnpm@11.9.0", "engines": { "node": ">=22" } }

Le gestionnaire de paquets est figé, non seulement les paquets. Un pnpm différent résout le fichier de verrouillage différemment, et c’est la couche en dessous de celle que la plupart des projets figent.

TypeScript est maintenu en 6.x avec la raison écrite : TypeScript 7 n’expose pas encore l’API programmatique dont dépend astro check, si bien que pnpm typecheck échoue purement et simplement en 7. Le verrou nomme la condition de sa levée, ce qui sépare une contrainte réfléchie d’une contrainte héritée.

Ce que ce dépôt ne fait pas

Être honnête sur les lacunes fait partie de l’étude de cas.

Pas de conteneur. Un fichier de verrouillage plus un gestionnaire de paquets figé reproduit le côté JavaScript ; les côtés Python et TeX dépendent de ce que le contributeur possède. pnpm figures:build n’a besoin que d’un Python d’origine, et pnpm course:pdf avertit au lieu d’échouer quand TeX est absent — un arbitrage délibéré pour qu’un contributeur sans chaîne d’outils puisse quand même livrer du contenu.

Pas de test de déterminisme de bout en bout en intégration continue. La régénération des jeux de données est déterministe et vérifiée à la main ; il n’existe pas de tâche d’intégration continue qui régénère tout et échoue sur un diff. Ce serait la prochaine chose à ajouter.

La documentation de passation est mince. CLAUDE.md et docs/DEFINITION_OF_DONE.md portent les décisions, ce qui est plus que la plupart des dépôts et moins que ce qu’exige la leçon 7.

Nommer les lacunes est l’essentiel. Une étude de cas qui revendique tout est une étude de cas dont personne ne peut apprendre, et les trois ci-dessus sont l’état honnête d’un dépôt par ailleurs inhabituellement strict avec lui-même.

Rapportez-le en entier

Reproducibility of this platform

  Data          20 CSV files generated by 17 seeded scripts. Regenerating all
                of them produces byte-identical output; `pnpm datasets:generate`
                followed by `git status` is the verification.

  Checks        7 fail the build (schema, references, locale, translation
                parity, topic-sector, synthetic-only, programme spine).
                20 test files and 4,212 assertions run first in CI.

  Output        Course PDFs, slide decks, figures and notebooks are committed
                and deterministic. SOURCE_DATE_EPOCH pins pdfTeX and pandoc.

  Environment   pnpm 11.9.0 and Node 22 pinned. TypeScript held at 6.x with
                the reason and the removal condition documented.

  Refused       A dataset not declared synthetic fails the build.

  Not done      No container; no CI job that regenerates everything and fails
                on a diff; handover documentation thinner than this course
                asks for.

La dernière ligne est celle à copier dans votre propre version. Une déclaration de reproductibilité sans section « pas fait » est une déclaration que personne n’a auditée.

La suite

C’est le cours, et c’est le dernier de l’ossature du programme.

Le fil qui traverse les vingt est le même. Un nombre dans un rapport de programme est une affirmation, et tout ce que cette plateforme enseigne porte sur ce qui doit être vrai pour que l’affirmation tienne — un dénominateur défendable, un intervalle qui dit votre degré de certitude, un groupe de comparaison qui en est un, un graphique qui n’en dit pas plus que les données, et une chaîne qui produit la même réponse quand quelqu’un d’autre l’exécute.

La dernière est celle qui rend les autres vérifiables. Une analyse que personne ne peut réexécuter est une analyse dont les autres propriétés doivent être prises sur parole, et ce public est jugé sur sa capacité à défendre un nombre en revue plutôt qu’à le produire.