ContribuerGuidePour contributeursS'applique de 4.5.0

Avant une pull request

This page in English Cette page sur le wiki GitHub

Une seule liste de ce qu'il faut lancer et vérifier avant d'ouvrir une pull request sur le moteur, pour que la CI confirme ce que vous savez déjà au lieu de vous l'apprendre.

Ce que vous obtenez

Une branche dont le premier palier est vert sur votre machine (formatage, lint, types, tests unitaires, barrières du jeu d'exemple), dont le changement de comportement est assumé, dont le fragment du CHANGELOG est là, et dont la description de pull request dit ce qui change et ce qui reste.

Contexte et versions

Le dépôt du moteur, sur une branche nommée comme le dit Conventions. Les commandes sont celles de la 4.4.0 ; les fragments du CHANGELOG existent depuis la 4.1.9, release-check:local depuis la 4.1.17.

Prérequis

Un dépôt préparé : Préparer son poste de développement, avec Python et ses modules (les tests d'assets en ont besoin) et le Chromium de Playwright.
Votre changement fait avec La boucle de développement.

Où lancer les commandes

Dans le dépôt du moteur, sur votre machine, sur votre branche. Lancez une suite de tests à la fois : deux suites côte à côte se disputent les mêmes cœurs et laissent des workers orphelins quand on les interrompt.

Étapes

Respectez les règles du contenu.
- Le gameplay reste déclaratif dans games/<id>/ ; la géométrie va dans layout/*.json, jamais tapée à la main.
- Chaque règle, choix, sujet, écouteur, bloc persistant et étape de script du schéma 3 a un id stable. npm run ids -- --write --map écrit ceux qui manquent dans les sources (État et sauvegardes).
- Aucun asset source privé, rien dont les droits commerciaux sont flous.

Formatage, lint et types.
```
# dans le dépôt du moteur
npm run quality
```
Elle lance, dans cet ordre : format:check (formatage Biome), lint:code (lint Biome), knip (fichiers, exports et dépendances inutilisés), tsc --noEmit avec tsconfig.json, tsc --noEmit -p tsconfig.strictest.json (chaque accès indexé vérifié dans src/), et lint:content (le lint de contenu). npm run format écrit le formatage ; un commit qui ne fait que reformater est un commit à part, listé dans .git-blame-ignore-revs (Conventions).

La suite unitaire.
```
# dans le dépôt du moteur
npm run check
```
check choisit le jeu, vérifie les types, puis lance test:node : tous les fichiers de test sauf les tests lourds du solveur (la nightly et le candidat les lancent) et les deux tests d'assets (étape suivante).

Les tests d'assets, qui demandent Python et ses modules d'image.
```
# dans le dépôt du moteur
npm run test:assets
```

Les barrières du jeu.
```
# dans le dépôt du moteur
npm run verify:game
```
Elle lance validate, solve, solve -- --chapters, verify:variants, i18n -- status, le lint de contenu et playtests, sur le jeu courant.

La référence de comportement. Un changement censé garder le comportement la laisse identique :
```
# dans le dépôt du moteur
npm run quality:baseline -- --check
```
Un changement qui modifie volontairement le comportement, ou qui ajoute un test, la réécrit avec npm run quality:baseline (qui écrit aussi les chiffres des README) et committe le résultat. Voir La référence de qualité.

La documentation, quand vous l'avez touchée, ou le code sur lequel repose une page :
```
# dans le dépôt du moteur
npm run docs:truth
npm run wiki -- check
```
wiki -- check se termine par ✔ … 0 error(s) ; Écrire la documentation dit comment les pages s'écrivent et se vérifient.

Le fragment du CHANGELOG. Une branche qui modifie src/, bridge/, tools/, scripts/, cli/, connectors/ ou games/ porte changes/<slug>.md (et changes/<slug>.log.md pour une entrée du LOG) :
```
# dans le dépôt du moteur
npm run changes -- --check
```
Elle affiche ✔ … a fragment or a CHANGELOG edit is there, or no code moved, ou le refus et ce qu'il faut écrire (Conventions).

Un changement visuel ou dans le navigateur : construisez pour la production, servez, jouez, et regardez les captures.
```
# dans le dépôt du moteur
npm run build:game
npm run preview -- --port 5173 &
npm run e2e:smoke -- http://127.0.0.1:5173/
```
e2e:smoke joue le build de production avec le harnais générique dans un Chromium de 844 × 390 ; les captures arrivent dans E2E_OUT (par défaut /tmp/e2e). Ouvrez-les. Arrêtez ensuite le serveur de prévisualisation (kill %1 dans le même shell).

La même chose, en une ligne. release-check:local enchaîne la plupart des étapes ci-dessus :
```
# dans le dépôt du moteur
npm run release-check:local
```
Elle lance quality, docs:truth, test:node, build:game (les barrières du jeu, le bundle, verify:dist, la vérification des spoilers, l'audit des assets) et quality:baseline -- --check --dist. Elle ne lance ni test:assets, ni changes -- --check, ni wiki -- check, ni le navigateur.

Ouvrez la pull request depuis .github/PULL_REQUEST_TEMPLATE.md, avec un titre comme le dit Conventions. Remplissez chaque section : « What changes » (ce qu'un joueur, un auteur ou un hébergeur voit de différent), « Checked », et « Not done, said as such » (« Nothing » quand il ne reste rien). Un changement visuel porte une capture dans la description.

La liste de chaque jalon (reprise de la feuille de route)

La feuille de route des jalons v1.3 à v2 avait sa propre liste, déroulée à chaque jalon ; elle est gardée ici telle qu'elle était écrite :

npm run validate && npm run solve && npm test && npm run build verts, CI verte, audit d'assets vert.
La démo utilise chaque nouvelle primitive au moins une fois et l'e2e la traverse (captures 844 × 390).
Une sauvegarde faite avec la version précédente de la démo se charge après migration (un test unitaire sur un JSON figé par jalon). Aujourd'hui, une sauvegarde de référence par version depuis la 3.0 vit dans tests/fixtures/saves/ et se joue jusqu'à la fin dans tests/save-v3.test.ts et dans la référence de qualité.
Une copie de src/engine dans le jeu privé : ses tests, son solveur et son e2e inchangés (à l'époque : 37 tests, une solution de 62 actions, l'e2e du jeu privé d'origine identiques).
MCP : npm run -s mcp liste les outils mis à jour ; une session d'IA neuve ajoute un script ou un événement à la démo en suivant seulement le guide de contenu.
Une release taguée avec ses notes, et la table « Versions » du README mise à jour. Le README nomme désormais la version courante dans sa section Documentation plutôt que dans une table ; les releases se font comme le dit Publier une release.

Résultat attendu, et comment le vérifier

Chaque commande ci-dessus finit au vert. Sur la pull request, pr-gate passe au vert une fois que chaque job du plan a réussi (La CI expliquée) ; un job que le plan épargne dit « not needed by the plan » et réussit.

Erreurs fréquentes

Symptôme	Cause	Correction
`format:check` échoue	Un fichier n'est pas formaté	`npm run format`, dans un commit à part s'il reformate plus que votre changement
`knip` nomme un export ou un fichier inutilisé	Du code mort laissé par le changement	Supprimez-le, ou utilisez-le
`✖ this branch changes the code and carries no fragment`	Pas de `changes/<slug>.md`	Écrivez-le (Conventions)
`✖ behaviour moved from tests/quality-baseline.json`	Une empreinte, un verdict, une sauvegarde de référence ou la surface d'API a bougé, ou un chiffre du README est en retard	La référence de qualité
`test:assets` échoue à l'import	Modules Python absents	`python3 -m pip install -r requirements.txt`
Le job de couverture de la CI avertit « coverage ratchet »	Un seuil est à trois points ou plus sous ce que les tests atteignent	Pas bloquant sur une pull request ; relevez-le (Le cliquet de couverture)

Fichiers ou données modifiés

npm run format réécrit des fichiers sources ; npm run quality:baseline réécrit tests/quality-baseline.json et les chiffres de README.md et README.fr.md ; npm run ids -- --write --map écrit des ids dans games/<id>/. Les vérifications elles-mêmes n'écrivent que sous .cache/ et /tmp/e2e.

Revenir en arrière

Une réécriture non voulue (format, quality:baseline) s'annule avec git restore <fichier>. Une exécution de tests interrompue peut laisser des workers Vitest en marche : arrêtez-les par leur numéro de processus (ps puis kill <pid>), pas par un motif.