From 7f72386547e696b377f494b670dc2534eb131ba0 Mon Sep 17 00:00:00 2001 From: mathieu Date: Sat, 22 Aug 2026 12:15:39 +0200 Subject: [PATCH] Consigne ce que le paquet YunoHost a appris de sa propre mesure MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Trois items ouverts d'IDEES.md instruits sur pieces, et deux conclusions renversees en chemin — c'est ce que ces notes servent a ne pas refaire. Le paquet n'avait presque rien a simplifier : neuf fichiers, 209 lignes de code, de 9 a 49 lignes chacun. Ce qui donnait l'impression de volume, ce sont les 306 lignes de commentaires, qui documentent chacune une panne reellement constatee. Tout le poids etait dans publier.sh, 1,4 fois le paquet reuni. Le menu interactif de choix de version paraissait le meilleur candidat a la coupe, jusqu'a ce que les neuf montees de version montrent six correctifs ET trois sauts mineurs. Il sert une fois sur trois : mesurer avant de tailler vaut aussi pour l'outillage. L'icone du paquet : logo.png n'est lu par personne. Les logos du catalogue vivent dans le depot YunoHost/apps, ou MaBibli n'est pas ; la tuile du portail accepte un logo televerse depuis la 12.1, et le manifeste exige deja 12.1.38. Il n'y a donc rien a corriger dans le depot. La RAM est mesuree et ram.runtime porte a 256M. Le pic n'est pas le lookup ISBN, contrairement a l'intuition, mais « Nouveautes » sur un auteur tres reedite — cas qui n'a pas encore ete mesure et qui croit avec le fonds. Le README cesse de decrire --archive-seule comme une brique de CI et retire le « --version est obligatoire ici », piege qui n'existe plus. Co-Authored-By: Claude Opus 5 --- CLAUDE.md | 132 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- IDEES.md | 48 ++++++++++++++++++-- README.md | 32 ++++++++++--- 3 files changed, 198 insertions(+), 14 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 7222efc..5700b3f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2006,10 +2006,134 @@ Les deux scripts sont fondus dans `build/publier.sh`, qui refuse maintenant de p **avant de compiler** si le tag existe déjà (en nommant le commit du tag et celui de HEAD) ou si le dépôt du code a des modifications non committées. -⚠️ Le mode `--archive-seule` conserve la brique réutilisable en CI, mais **sous le même -nom** : il compile et archive sans toucher ni au manifeste ni à git, donc il ne peut -rien laisser à moitié publié. Ne pas recréer de second script — c'est la coexistence de -deux commandes voisines qui était le défaut, pas leur contenu. +⚠️ Le mode `--archive-seule` conserve, **sous le même nom**, ce que le second script +savait faire : il compile et archive sans toucher ni au manifeste ni à git, donc il ne +peut rien laisser à moitié publié. Ne pas recréer de second script — c'est la +coexistence de deux commandes voisines qui était le défaut, pas leur contenu. + +### ⚠️ `--archive-seule` n'est PAS une brique de CI — rangé le 2026-08-22 + +C'est ce que cette section a affirmé jusqu'au 2026-08-22, et c'était faux. Le `README` +du dépôt du code s'en sert depuis toujours pour tout autre chose, sur une trentaine de +lignes : c'est le **chemin de reprise à la main** quand `publier.sh` échoue en cours de +route (section B.3). + +La distinction n'est pas académique. Sur la foi de « une brique pour une CI qui n'existe +pas », le mode partait à la casse ; sur celle de « le seul moyen de finir une +publication interrompue sans re-déclencher les garde-fous », il reste. **Un usage qui +n'a jamais servi n'est pas un usage inutile quand c'est un extincteur** — et l'historique +du shell confirme qu'il n'a effectivement jamais été lancé, faute d'avoir jamais eu à +reprendre à la main. + +Ce que le rangement a changé, et qui vaut au-delà de ce script : + +| Avant | Après | +|---|---| +| 8 ramifications sur `archive_seule`, dont **3 assouplissaient un garde-fou** | 5, dont **une seule** exprime la différence de mode | +| le dépôt sale n'était **pas signalé du tout** — l'archive contenait en silence du travail non committé | tous les contrôles s'exécutent et **avertissent** | +| la version retombait sur celle du **manifeste**, donc sur la version **déjà publiée** | même calcul dans les deux modes | +| le dépôt git n'était exigé qu'en publication (4 tests `-d .git` plus bas) | exigé une fois, en tête ; le reste du script est inconditionnel | + +⚠️ **Le piège que la version retombée sur le manifeste créait était documenté au lieu +d'être corrigé** : le `README` portait un « `--version` est obligatoire ici », qui +n'existe plus. Une reprise veut la version qu'on était en train de publier — c'est +exactement ce que l'incrément propose. + +⚠️ **`refuser()` sépare le CONSTAT du CONSEIL**, et ce n'est pas de la cosmétique : le +constat reste vrai dans les deux modes, le conseil non. « Choisissez un numéro libre » +est juste pour une publication et faux en reprise, où le tag visé est justement celui +qu'on veut retrouver. + +⚠️ **Les cinq variables d'environnement jumelles ont disparu** (`MABIBLI_SOURCE_DIR`, +`MABIBLI_BASE_URL`, `MABIBLI_URL_RELEASES`, `MABIBLI_OUTPUT_DIR`, `MABIBLI_VERSION`) : +chacune doublait une option qu'elle ne faisait que répéter, l'aide en listait dix pour +cinq réglages, et rien ne disait laquelle l'emportait. Ne pas les réintroduire pour une +CI hypothétique — une CI passe des options aussi bien que des variables. + +### Ce que la mesure a montré, et qu'il ne faut pas re-chercher ailleurs + +Le paquet lui-même **n'a rien à simplifier** : neuf fichiers, **209 lignes de code** au +total, de 9 à 49 lignes chacun. Ce qui donne l'impression de volume, ce sont les **306 +lignes de commentaires** — qui documentent chacune une panne réellement constatée +(guillemetage d'`Environment=`, `ProtectHome=tmpfs`, `WorkingDirectory`, `.backup` en +WAL). Les couper rendrait les fichiers plus courts et le paquet plus dangereux. + +Tout le poids est dans `publier.sh` : **298 lignes de code avant rangement, soit 1,4 +fois tout le paquet réuni**, dont un tiers pour choisir un numéro de version et analyser +des drapeaux. + +⚠️ **Le menu interactif de version, lui, reste** : il paraissait le meilleur candidat à +la coupe, jusqu'à ce que les neuf montées de version montrent **six correctifs et trois +sauts mineurs**. Il sert une fois sur trois. Mesurer avant de tailler vaut aussi pour +l'outillage. + +### L'icône du paquet — `logo.png` n'est lu par personne (établi le 2026-08-22) + +`mabibli_ynh/logo.png` existe (256×256, RGBA, 824 o, même dessin que l'application) et +**aucun composant ne le lit**. La question posée par IDEES.md est donc tranchée : + +- **le catalogue YunoHost ne lit pas le dépôt de l'application.** Les logos vivent dans + le dépôt *du catalogue* (`YunoHost/apps`, dossier `logos/`, nommé d'après l'identifiant + de l'app). MaBibli n'y est pas, et n'a pas vocation à y être : il s'installe depuis une + URL Gitea privée ; +- **la tuile du portail** affichait un substitut pour toute application hors catalogue en + YunoHost 12.0, sans recours. **Depuis 12.1, le logo se téléverse** — et le manifeste + exige déjà `yunohost >= 12.1.38`. + +⚠️ **Il n'y a donc rien à corriger dans le dépôt** : c'est un geste sur le serveur, dans +l'interface d'administration, avec le fichier déjà présent. Ne pas repartir en chasse au +chemin de fichier manquant, ni ajouter une clé `logo` au manifeste — le format v2 n'en a +pas. + +⚠️ À ne pas confondre avec les icônes **de la PWA** (`favicon.png`, `icon-192.png`, +`icon-512.png`), qui sont dans le dépôt du code et en place depuis le lot A3. + +### `ram.runtime` mesuré et porté à 256M (2026-08-22) + +`50M` et `200M` étaient posés à l'estime. **Mesuré sur le serveur** : pic réel de +**208 793 600 o, soit 199,1 Mio** — contre 200M déclarés, c'est-à-dire **0,4 % de +marge**. Porté à `256M` ; `ram.build` reste à `50M`. YunoHost s'en sert pour refuser une installation : +trop haut, on interdit une installation qui aurait marché ; trop bas, on la laisse finir +en OOM. + +⚠️ **Rien d'utile ne sort d'une machine de développement.** Un `dotnet run` ne dit rien +de la consommation d'un publish self-contained sous systemd — namespaces, durcissement, +absence de SDK. Le relevé utile est celui du service en marche, après une navigation +ordinaire **puis** après un lookup ISBN (c'est là que le client HTTP et le parseur de +notices travaillent) : + +``` +cat /sys/fs/cgroup/system.slice/mabibli.service/memory.peak +``` + +⚠️ **`systemctl show -p MemoryPeak` ne renvoie RIEN sur le serveur** (mesuré le +2026-08-22) : la propriété n'y est pas exposée, et la commande réussit en silence. On +croit lire un pic, on lit un instantané. Passer par le cgroup, qui garde le maximum. + +⚠️ **`memory.current` inclut le cache de fichiers**, donc les 69 Mo de binaire +self-contained mappés. Une bonne part du chiffre est récupérable sous pression et n'est +pas un besoin réel — et le GC de .NET laisse en outre enfler son tas tant que la machine +est large. Le relevé majore donc le besoin, il ne le mesure pas. + +⚠️ **Le pic n'est PAS le lookup ISBN**, contrairement à l'intuition : une notice. C'est +le bouton **« Nouveautés »** d'un auteur très réédité — jusqu'à dix pages de 100 notices +SRU en parallèle, leur XML parsé, plus le catalogue entier chargé pour le rapprochement. + +⚠️ **Ce cas-là n'a pas encore été mesuré** : les 199,1 Mio l'ont été pendant un lookup +ISBN. Le vrai plafond est donc au-dessus, et il **croît avec la taille du fonds**, le +rapprochement chargeant tout le catalogue. À reprendre quand la bibliothèque aura +beaucoup grossi. + +⚠️ **L'asymétrie qui a tranché la valeur** : déclarer trop haut refuse une installation +qui aurait marché — visible, immédiat, contournable en connaissance de cause. Déclarer +trop bas laisse l'installation se faire pour finir en OOM plus tard, sous une opération +lourde, sans que rien ne désigne la cause. Même raisonnement que « une tranche d'ISBN en +moins se lit encore ; une tranche fausse trompe ». + +⚠️ **`ram.build` ne désigne pas une compilation** : rien n'est compilé sur le serveur, +c'est tout l'intérêt du self-contained. Il couvre le téléchargement et la +**décompression** d'une archive de 69 Mo. Chercher la valeur du côté d'un build .NET +donnerait un chiffre juste répondant à la mauvaise question. ### Deux pièges systemd, tous deux invisibles hors d'un vrai serveur diff --git a/IDEES.md b/IDEES.md index 954e90a..a19f85f 100644 --- a/IDEES.md +++ b/IDEES.md @@ -736,6 +736,35 @@ en second rideau** et l'**EAN-2 à confirmer en kiosque** — la série du 2026- ## Simplifier `mabibli_ynh` +✅ **Traité le 2026-08-22** — voir `CLAUDE.md`, « `--archive-seule` n'est PAS une brique +de CI » et « Ce que la mesure a montré ». Le texte d'origine est conservé ci-dessous : il +dit le besoin, que la décision ne remplace pas. + +**Le diagnostic n'était pas celui attendu.** Mesuré : le paquet fait **209 lignes de code** +pour **306 de commentaires**, ses neuf fichiers pesant de 9 à 49 lignes chacun. Il n'y +avait rien à y couper. Tout le poids est dans `publier.sh` (298 lignes de code, 1,4 fois +le paquet réuni). Ce qui a été fait : + +- `--archive-seule` **rangé, pas retiré** : ses 8 ramifications tombent à 5, dont une + seule exprime la différence de mode. ⚠️ Il avait failli être supprimé sur la foi d'une + justification fausse (« brique de CI ») ; le `README` montrait qu'il est le chemin de + reprise après échec ; +- les **cinq variables d'environnement jumelles** supprimées ; +- deux défauts corrigés au passage : le dépôt sale n'était **pas signalé** en + `--archive-seule`, et la version y retombait sur celle **déjà publiée** ; +- `build/dist` ramené de **680 Mo à 205 Mo** (trois dernières versions), et les deux + `doc/*_fr.md`, identiques à leurs jumeaux, supprimés. + +⚠️ **Le menu interactif de choix de version reste** : c'était le meilleur candidat à la +coupe sur le papier, jusqu'à ce que les neuf montées de version montrent six correctifs +**et trois sauts mineurs**. Mesurer avant de tailler vaut aussi pour l'outillage. + +⚠️ **Écarté avec l'utilisateur le 2026-08-22** : automatiser le dépôt de la release dans +Gitea via son API. Cela aurait fait passer la publication de trois gestes à deux, au prix +d'un jeton d'accès à posséder et à renouveler. Le téléversement reste manuel. + +--- + Demande telle quelle : « retravailler la partie YunoHost pour la simplifier ». Rien n'est diagnostiqué à ce stade — le paquet **fonctionne** (installé, mis à jour, sauvegardé et restauré sur un vrai serveur, voir `CLAUDE.md`), il s'agit de le rendre plus simple à lire et à @@ -759,13 +788,26 @@ lignes, ou moins de choses à savoir pour publier une version ? Ce ne sont pas l ## L'icône du paquet -`mabibli_ynh/logo.png` **existe** (824 o, 256×256, même dessin que l'application). Reste à -établir ce qui manque exactement — le catalogue YunoHost et la tuile du portail ne lisent pas -forcément le même fichier au même endroit. ⚠️ À ne pas confondre avec les icônes **de la PWA** +✅ **Tranché le 2026-08-22** — voir `CLAUDE.md`, « L'icône du paquet ». Réponse : **le +fichier n'est lu par personne**, et il n'y a **rien à corriger dans le dépôt**. Les logos +du catalogue vivent dans le dépôt `YunoHost/apps`, où MaBibli n'est pas ; la tuile du +portail accepte un logo téléversé **depuis la 12.1**, et le manifeste exige déjà +`>= 12.1.38`. C'est un geste sur le serveur, avec le fichier déjà présent — reste à le +faire, et à vérifier sur place l'écran exact de l'interface 12.1. + +`mabibli_ynh/logo.png` **existe** (824 o, 256×256, même dessin que l'application). ⚠️ À ne pas confondre avec les icônes **de la PWA** (`favicon.png`, `icon-192.png`, `icon-512.png`), qui sont dans le dépôt du code et déjà en place. ## Ajuster la RAM déclarée au plus près du réel +✅ **Mesuré et tranché le 2026-08-22** — voir `CLAUDE.md`, « `ram.runtime` mesuré et +porté à 256M ». Pic réel **199,1 Mio** contre 200M déclarés, soit **0,4 % de marge** : +`ram.runtime` passe à `256M`, `ram.build` reste à `50M`. + +⚠️ **Reste ouvert, mais nommé** : le cas plafond (« Nouveautés » sur un auteur très +réédité) n'a pas été mesuré, et il croît avec la taille du fonds. À reprendre quand la +bibliothèque aura beaucoup grossi. + `manifest.toml` annonce `ram.build = "50M"` et `ram.runtime = "200M"` — des valeurs **posées à l'estime**, jamais mesurées. YunoHost s'en sert pour refuser une installation sur une machine trop petite : trop haut, on interdit une installation qui aurait marché ; trop bas, on la laisse diff --git a/README.md b/README.md index 93fdf04..0cd6513 100644 --- a/README.md +++ b/README.md @@ -95,7 +95,7 @@ fichier est le point d'entrée unique du projet. | `conf/nginx.conf` | Reverse proxy et intégration SSOwat | | `scripts/_common.sh` | Variables partagées et sauvegarde/restauration cohérente de la base SQLite | | `scripts/install` `remove` `upgrade` `backup` `restore` | Cycle de vie de l'application | -| `build/publier.sh` | **Seul script de publication** : version, archive, manifeste, commit et push du paquet, tag et push du code. `--archive-seule` compile sans rien publier | +| `build/publier.sh` | **Seul script de publication** : version, archive, manifeste, commit et push du paquet, tag et push du code. `--archive-seule` compile et archive sans rien publier, pour reprendre après un échec | | `doc/DESCRIPTION.md` `doc/ADMIN.md` | Textes affichés par YunoHost lui-même (catalogue et interface d'administration) — ils doivent rester dans ce dépôt | ### Points de conception @@ -136,8 +136,8 @@ a existé jusqu'au 2026-08-21 : il compilait, archivait et réécrivait le manif charge pour l'appelant de committer. Son nom inspirait plus confiance que celui du vrai point d'entrée, et lancé seul il produisait exactement la panne du 2026-08-21 — un `manifest.toml` corrigé mais non poussé, et une release `v0.4.0` contenant en réalité six -commits de plus que son tag. Les deux scripts sont fondus ; la brique réutilisable -subsiste sous la même commande : +commits de plus que son tag. Les deux scripts sont fondus ; ce que le second savait +faire subsiste sous la même commande : ```bash ./build/publier.sh --archive-seule @@ -146,6 +146,17 @@ subsiste sous la même commande : Ce mode compile et archive, **sans toucher ni au manifeste ni à git** : il ne peut donc rien laisser à moitié publié. +⚠️ **À quoi il sert vraiment** : à **reprendre une publication à la main** quand +`publier.sh` a échoué en cours de route (voir B.3). Ce n'est pas « une brique pour une +CI » — c'était la justification écrite jusqu'au 2026-08-22, et elle désignait un usage +qui n'a jamais eu lieu, là où la reprise après échec, elle, est documentée pas à pas. + +⚠️ **Les contrôles ne sont PAS désactivés dans ce mode**, contrairement à ce qui a été +vrai jusqu'au 2026-08-22 : ils s'exécutent tous, et **avertissent** au lieu de refuser, +puisque rien n'est publié et que rien ne peut donc mentir. Le dépôt sale, en +particulier, n'était alors pas signalé du tout — l'archive contenait en silence du +travail non committé. + Ce script compile ce dépôt (`mabibli`) en `Release` self-contained, **vérifie** le résultat (binaire présent, `wwwroot/` embarqué, toutes les ressources d'`index.html` réellement sur disque, aucun placeholder d'empreinte non substitué), produit une @@ -175,7 +186,10 @@ Il refuse par ailleurs de publier dans deux cas, **avant de compiler** : | le tag `vX.Y.Z` existe déjà | une release qui ne contient pas le code que son tag désigne — arrivé le 2026-08-21, six commits d'écart, sans que rien ne le signale | | le dépôt du code a des modifications non committées | une archive contenant du travail que le tag, lui, ne contient pas | -Dans les deux cas il nomme le commit en cause et rappelle `--patch` ou `--archive-seule`. +Dans les deux cas il nomme le commit en cause et rappelle `--patch`. ⚠️ En +`--archive-seule`, les mêmes contrôles **avertissent** au lieu de refuser — le constat +s'affiche, le conseil « choisissez un numéro libre » non : en reprise, le tag visé +est justement celui qu'on veut retrouver. **La marche à suivre complète et éprouvée**, pour les cas que `publier.sh` ne couvre pas — première mise en production, montée de version pas à pas, retour arrière, @@ -343,11 +357,15 @@ cours de route. Le code est prêt et committé dans `mabibli`. Depuis `mabibli_ynh` : ```bash -./build/publier.sh --archive-seule --version 0.1.1 +./build/publier.sh --archive-seule --patch ``` -⚠️ **`--version` est obligatoire ici.** En `--archive-seule`, sans lui, le script déduit -la version de `manifest.toml` et reproduirait 0.1.0. +⚠️ **`--version` n'est plus obligatoire ici, depuis le 2026-08-22.** Le mode reprenait +alors la version de `manifest.toml` — c'est-à-dire celle **déjà publiée** — et +reproduisait donc 0.1.0 tant qu'on ne le corrigeait pas à la main. Les deux modes +calculent maintenant la version de la même façon : `--patch` propose 0.1.1, et +`--version` ne sert plus qu'à viser un autre numéro (par exemple celui d'un tag déjà +créé, si la publication a échoué après le tag). ⚠️ **`--archive-seule` ne touche pas au manifeste** : `version` (avec son suffixe `~ynh1` — une nouvelle version applicative repart toujours de 1), `amd64.url` et