From b18e60979a026ea989a051e7e1cee934d4ed0659 Mon Sep 17 00:00:00 2001 From: Paul Schneider Date: Sun, 14 Jun 2026 17:22:50 +0100 Subject: [PATCH] docs: add trunk-cleanup challenge brief MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Énoncé du défi : aligner main sur l'intention trunk qui a déjà opéré sur themeok, libérer le dépôt du code inutile, bien nettoyer CSS/JS, sans casser le JS et le CSS de _Layout.cshtml. Introduire immédiatement des tests d'UI automatisés comme garde-fou. Le document contient : - Énoncé du défi - État actuel des 3 branches (themeok, main, refac/js-bundle) - Résultats du diagnostic de main (cause racine : contenu vide + erreur JS sur carousel vide, pas un problème de fichiers servis) - 6 critères d'acceptation vérifiables - Stratégie de tests UI automatisés (Playwright C#) - Plan d'attaque en 6 étapes - 5 risques identifiés (cache navigateur, double binding Kestrel, .env non versionné, ports utilisés, quiproquos de branches) - Todo court/moyen/long terme - Annexes : environnement d'exécution, procédure make reinstall Le diagnostic a été reproduit en worktree diag/main sur ports 5060/5061, en surchargeant la config Kestrel via variables d'environnement pour ne pas écraser le service systemd yavscOrg sur port 3002. --- doc/challenges/2026-06-14-trunk-cleanup.md | 424 +++++++++++++++++++++ 1 file changed, 424 insertions(+) create mode 100644 doc/challenges/2026-06-14-trunk-cleanup.md diff --git a/doc/challenges/2026-06-14-trunk-cleanup.md b/doc/challenges/2026-06-14-trunk-cleanup.md new file mode 100644 index 00000000..a867b108 --- /dev/null +++ b/doc/challenges/2026-06-14-trunk-cleanup.md @@ -0,0 +1,424 @@ +# Défi : aligner `main` sur l'intention trunk + nettoyage CSS/JS + +> Énoncé : 2026-06-14, par Paul Schneider. +> Statut : **ouvert**. + +## Énoncé + +Atteindre, sur la branche `main` et en mode trunk, l'état +intentionnel qui a déjà opéré sur la branche `themeok` (la +référence). Concrètement : + +1. **Libérer le dépôt de son code inutile** : retirer les assets + vendor non utilisés (Quill, dropzone.min.css, jquery-ui si plus + personne ne s'en sert, etc.) et tout ce qui n'est référencé + nulle part dans le code applicatif. + +2. **Bien nettoyer le CSS et le JS** : déplacer les vendor libs + sous un régime cohérent (npm + esbuild), arrêter le + double-tracking (fichiers versionnés + bundles esbuild), poser + des conventions claires. + +3. **À minima, ne pas casser** le JS et le CSS de + `_Layout.cshtml`. C'est l'invariant non-négociable. + +4. **Introduire immédiatement** des tests d'UI automatisés pour + servir de garde-fou contre la régression, à chaque commit. + +## Pourquoi maintenant + +`themeok` est devenu, dans la pratique, la branche de référence +pour le look et le comportement front. `main` n'a pas reçu les +commits correctifs de `themeok`, et son état est plus dégradé +(caches navigateur, état runtime, scripts inline qui plantent sur +du contenu vide). + +Tant que la divergence existe, on risque de : +- cherry-picker à la main en ratant un commit, +- ne pas voir une régression front parce qu'on ne teste pas en + navigateur, +- accumuler de la dette visuelle sur `main` jusqu'à un point de + non-retour. + +## État actuel + +### `themeok` (référence, à 4 commits devant `main`) + +``` +ec8fd4b6 fix(cookies): set Identity cookies to SameSite=Lax in dev +76fef567 chore: remove Quill +379413f3 chore: snapshot of themeok branch as visual reference +d71490f5 chore: stop tracking vendor lib files +31906a78 WIP : Js and css cleanup ← point de départ du WIP +30587248 ← ancêtre commun avec main +``` + +État du working tree : propre. `dotnet test` : 11/11 verts. +Serveur dev local démarre sans warning (à part le certificat +HTTPS de dev non trusted, sans gravité). + +### `main` (à remettre au niveau) + +``` +2a9760ca docs: roadmap à jour, archive TODO.fr +8f768240 WIP: refactoring pour déploiement +30587248 ← même ancêtre commun +``` + +État runtime connu : **look catastrophique** sur +`http://localhost:5000`. Diagnostic (cf. +[§ Résultats du diagnostic](#résultats-du-diagnostic)) : +- Le HTML est rendu correctement, toutes les CSS et JS sont + servies en HTTP 200. +- Le "look catastrophique" vient du **contenu vide** (Home/Index + n'a aucune section) et d'une **erreur JS** dans un script + inline qui plante quand le carousel est vide. + +### `refac/js-bundle` (suspendue) + +``` +fad7fc8d refac: remove jQuery + jQuery UI imports from datetime +79658c84 refac: remove vendor imports from chat entry +6455178b refac: load jQuery + Bootstrap as global scripts in _Layout +ed7522c5 fix: drop nuget bootstrap and popper.js, npm bundles +196f4b0b chore: gitignore node_modules, build/, wwwroot/lib +``` + +Trois commits de migration jQuery-en-script-global. **Pas encore +fusionnés dans `themeok` ni dans `main`**. À intégrer dans le +plan, mais pas en première priorité. + +## Résultats du diagnostic + +Reproduit en worktree `~/Workspace/yavsc-main/` sur branche +`diag/main` (basée sur `main@2a9760ca`). + +### Procédure + +```bash +git worktree add -b diag/main ../yavsc-main main +cp ~/Workspace/yavsc/.env ~/Workspace/yavsc-main/.env +# Forcer le port : appsettings de main contient +# "Kestrel.Endpoints.Http.Url": "http://localhost:3002" qui entre +# en conflit avec le port 5000 du dev settings. Override par env : +cd ~/Workspace/yavsc-main/src/Yavsc.Org +Kestrel__Endpoints__Http__Url=http://localhost:5060 \ +Kestrel__Endpoints__Https__Url=https://localhost:5061 \ +ConnectionStrings__YavscConnection="Server=localhost;Port=5432;Database=yavscdev;Username=yavscdev;Password=***" \ +ASPNETCORE_ENVIRONMENT=Development \ +dotnet bin/Debug/net10.0/Yavsc.Org.dll +``` + +> **Note de Paul** : la procédure d'install / dev principale +> est en fait `cd contrib; make reinstall` (qui build en +> Release, copie vers `/srv/www/yavsc/`, et gere le service +> systemd `yavscOrg` sur port 3002). Le `dotnet run` direct +> n'est qu'un raccourci de debug. Le diagnostic ci-dessus a +> été fait en `dotnet run` sur un port libre (5060) parce que +> le port 3002 etait deja occupe par le service systemd +> existant. + +### Fichiers servis (HTTP 200, taille correcte) + +| URL | Code | Taille | +|--------------------------------------------------|------|---------| +| `/lib/jquery-ui/jquery-ui.min.css` | 200 | 30770 | +| `/lib/bootstrap.quartz.min.css` | 200 | 244113 | +| `/css/site.css` | 200 | 3009 | +| `/lib/jquery-ui/external/jquery/jquery.js` | 200 | 285314 | +| `/lib/jquery-ui/jquery-ui.js` | 200 | 521054 | +| `/lib/bootstrap/dist/js/bootstrap.bundle.min.js` | 200 | 80721 | +| `/js/site.js` | 200 | 364 | +| `/lib/bootstrap/js/carousel.js` | 200 | 7141 | + +### HTML rendu (extrait du ``) + +```html + + +
+ +
+ + +``` + +### Cause racine + +1. Le HTML est structurellement correct : navbar Bootstrap 5 + `bg-dark`, carousel Bootstrap 4 (`data-ride`), container + Bootstrap. Toutes les CSS et JS sont chargées. + +2. Le **carousel est vide** (`
` sans + enfant `.item`). Le script inline + `car.children('.carousel-inner').first().children('.item').first()` + retourne `null` → `fi.children(...)` lève + `TypeError: Cannot read properties of null` → erreur console + qui stoppe la chaîne d'initialisation. + +3. Le **container principal est vide** : aucune section de + contenu → page visuellement blanche malgré le BG art. + +### Diff `main` vs `themeok` (fichiers versionnés) + +| Fichier | Diff | +|------------------------------------------------|-------------| +| `_Layout.cshtml` | identique | +| `_Nav.cshtml` | identique | +| `site.css` | identique | +| `_Layout.cshtml.css` (Razor scoped) | identique | +| `appsettings-org.Development.json` | identique | +| `appsettings-org.json` (production) | `Kestrel.Endpoints.Http.Url` = `3002` sur main, absent sur themeok | + +Donc **structurellement, `main` et `themeok` servent le même +HTML** quand on les lance en dev. La différence visible est due +au contenu des vues, pas aux fichiers de structure. + +## Critères d'acceptation + +Le défi est résolu quand : + +- [ ] **CA1** : `main` contient les 4 commits de `themeok` + (`d71490f5`, `379413f3`, `76fef567`, `ec8fd4b6`) — par merge ou + cherry-pick. +- [ ] **CA2** : la branche `refac/js-bundle` est mergée (ou + re-intégrée) sur `main`, via un commit explicite (pas un + merge fast-forward silencieux). +- [ ] **CA3** : un test d'UI automatisé (Playwright) existe et + passe sur `main` ET sur `themeok`. Le test vérifie au minimum : + - la page d'accueil répond 200, + - le HTML contient la navbar Bootstrap, + - la CSS `bootstrap.quartz.min.css` est chargée sans erreur, + - aucun script `