J7 — Contribuer

L’objectif du jour : une première contribution qui passe le pipeline du premier coup — et savoir lire le pipeline quand elle ne passe pas.

Durée réaliste	une journée, contribution comprise
Prérequis	J1 (l’environnement) et J3 (savoir où va votre changement)

Les commandes, dans l’ordre de la CI

C’est le même ordre, et ce n’est pas un hasard : le reproduire en local vous évite d’apprendre l’échec sur GitHub.

bun run lint        # Biome
bun run typecheck   # TypeScript, sur tout le workspace
bun run build       # AVANT les tests — voir plus bas
bun run test        # Vitest côté TS, Gradle côté solveur

Deux commandes de plus, que la CI ne joue pas :

Commande	Ce qu’elle fait	Quand la lancer
bun run format	Biome, en écriture — corrige au lieu de signaler	avant de committer
bun run test:contract	l’équivalence de scoring entre le moteur TypeScript et le solveur JVM	dès que vous touchez à une contrainte ou au contrat de solve

test:contract n’est dans aucun job de la CI. Si votre changement touche au scoring, cette vérification n’existe que si vous la lancez.

Le raccourci du pro

bun run test:all existe aussi : il joue les suites de tous les projets TypeScript dans un seul Vitest, sans le cache par paquet de Turbo. Au quotidien, bun run test est préférable — il ne rejoue que ce qui a changé.

Ce que la CI exécute vraiment

Deux jobs dans .github/workflows/ci.yml, et le second attend le premier.

1. verify — lint, typecheck, build, test, avec PostgreSQL et Redis démarrés en services, aux mêmes images et aux mêmes identifiants que docker-compose.yml.
2. lighthouse — construit tout le dépôt, puis mesure le site vitrine. Il est bloquant : une story de section qui dégrade la performance du site marketing ne peut pas être fusionnée. Ce n’est pas un rapport décoratif.

Les quatre choses que ce fichier sait et que vous ignorez

Elles sont écrites en commentaires dans ci.yml — les voici en clair, parce qu’elles ont chacune coûté du temps à quelqu’un.

1. Les suites de bout en bout d’apps/api se sautent d’elles-mêmes. Chaque test commence par if (!pgUp) return ctx.skip(). La convention garde bun run test utilisable sans Docker, mais elle a un jour réduit la CI à des tests unitaires — quelque 277 vérifications, tous les chemins HTTP, toutes les isolations RLS, les workers d’import et de solve — en rapportant vert. D’où les services déclarés dans le job.

2. Le rôle beemyschool_app n’est pas provisionné en CI, volontairement. Chaque suite crée sa propre base et joue migrateDb(), dont la migration 0000 crée ce rôle. Le provisionner une seconde fois dans le workflow, c’est le laisser diverger de la migration.

3. build passe avant test. Les gardes du site vitrine lisent dist/ : elles vérifient ce qui a été émis, pas ce que les sources ont l’intention d’émettre. Sans build préalable, elles se sautent en silence et l’étape passe en ne vérifiant rien.

4. Lighthouse tourne après verify, jamais avant. Mesurer une build qui ne compile pas ne vaut rien, et une exécution de Chrome coûte une minute.

Les conventions

• Le code est en anglais — noms, commentaires, messages de commit. Le contenu est en français — l’interface, la documentation, ce site.
• Bun, jamais npm ni pnpm. Biome, jamais ESLint ni Prettier. Les deux règles se lisent dans le dépôt : bun.lock d’un côté, biome.json de l’autre.
• La documentation part dans la même pull request que la fonctionnalité. Une page de ce site qui décrit un écran doit bouger quand l’écran bouge ; livrée plus tard, elle ne l’est jamais.
• Ce qui touche docs/ reste dans docs/. Le dossier porte la documentation de conception — contrats, décisions, spécifications. Ce site porte l’usage. On lie, on ne duplique pas.

Le gabarit de pull request

.github/pull_request_template.md se remplit tout seul dans la description de votre PR. Dix lignes, dont la seule qui compte vraiment : la case documentation, avec ses trois issues.

• mise à jour dans cette PR — les pages concernées ;
• pas nécessaire, parce que… — une réponse parfaitement légitime, à condition de dire pourquoi ;
• suivie par une story — avec sa référence.

Trois cases plutôt qu’une, parce qu’une case unique se coche par réflexe. Le gabarit est un aide-mémoire, pas un contrôle : ce qu’il empêche, c’est qu’un écran change sans que la page qui le décrit bouge — après quoi le site ment, et personne ne s’en aperçoit avant un client.

Le dépôt n’a pas de CONTRIBUTING.md : le reste des conventions vit dans les revues, et ici.

Votre première contribution

Une contribution réaliste et complète, qui traverse la chaîne sans être risquée : ajouter un champ optionnel à un contrat existant et le faire remonter jusqu’à l’écran — l’exercice de J5.

Elle a le mérite de toucher tout ce qui compte : un schéma partagé, une migration, un DTO, la chaîne OpenAPI, le client généré, un écran, et les tests des deux côtés. Si elle passe, vous savez livrer.

Avant de pousser :

bun run format && bun run lint && bun run typecheck && bun run build && bun run test

Le piège du jour

Une suite verte peut n'avoir rien vérifié

C’est le piège le plus coûteux du dépôt, parce qu’il ne ressemble pas à un problème : il ressemble à un succès.

Deux mécanismes de saut silencieux se cumulent :

• sans Docker, les suites de bout en bout d’apps/api se sautent test par test — plus aucun chemin HTTP, plus aucune isolation RLS n’est vérifiée ;
• sans JVM locale, apps/solver/scripts/gradlew-if-java.sh saute la tâche Gradle en affichant une ligne — que le résumé de Turbo noie sous les autres paquets.

Ce que vous observez : bun run test se termine par « successful », et votre régression part en revue.

Comment vous en sortez : avant de pousser un changement qui touche l’API, la base ou le solveur, vérifiez que l’infrastructure tourne — docker compose ps — et lisez le nombre de tests exécutés, pas seulement la couleur. Un chiffre qui s’effondre d’une exécution à l’autre est le seul signal que vous aurez.

Ce qui doit exister à la fin de la journée

• Les cinq commandes passent en local, dans l’ordre de la CI
• Vous savez quelles suites se sautent, et à quelle condition
• Vous savez que test:contract n’est joué par personne d’autre que vous
• Votre première pull request est ouverte, documentation comprise
• Le job verify est vert, et le job lighthouse aussi

Et après

Le parcours s’arrête ici, mais deux réflexes le prolongent.

Rejouez le produit du point de vue de l’utilisateur. Si vous n’avez pas encore fait le chemin de 2 heures, faites-le : placer un cours et lire une heatmap change la façon dont on lit le code du scoring.

Servez-vous de docs/. Les trente et un documents du dossier répondent aux « pourquoi » que ce parcours a délibérément laissés de côté ; la page d’entrée dit lequel ouvrir pour quelle question.