6.6 KiB
Manuel de référence — Archicratie Web Edition (Site + Gitea + Runner)
Ce manuel explique comment utiliser et maintenir l’outil d’édition :
- Site Astro “Archicratie – Web Edition”
- Proposer (tickets Gitea pré-remplis)
- Apply-ticket (application semi-automatique dans le contenu)
- Contrat d’ancres (citabilité) + tests
- CI Gitea Actions + ds220-runner (DS220+)
Objectif : une boucle éditoriale reproductible, opposable, sûre, et testée.
0) Glossaire minimal (anti-jargon)
- PR (Pull Request) : demande de fusion d’une branche vers
master. - PAT (Personal Access Token) : jeton d’accès Gitea utilisé comme “mot de passe” pour API/Git.
- Anchor / Ancre : identifiant stable d’un paragraphe (ex:
p-8-0e65838d) utilisable dans une URL#.... - Churn : variation des ancres d’une page entre deux builds (mesure de stabilité).
- dist/ : sortie buildée (artefact), jamais la “source de vérité”.
- CI : automatisation (build + tests) à chaque push/PR.
1) Pré-requis (poste local)
Outils
- Node.js + npm
- Git
- (Optionnel) Python3 pour scripts de debug ponctuels
Accès
- Compte Gitea avec droits sur le repo
- Un PAT Gitea
- Accès au site local (dev) et/ou build (dist)
2) Vue d’ensemble : la boucle éditoriale (rituel)
Boucle standard (la “cadence courte”)
- Sur le site, cliquer Proposer sur un paragraphe.
- Choisir Type (Correction / Fact-check), puis Category.
- Gitea ouvre un ticket pré-rempli (Chemin/URL/Ancre + texte actuel).
- Rédiger la Proposition (remplacer par) + Justification.
- En local :
node scripts/apply-ticket.mjs <num>(d’abord--dry-run)npm run test:anchorsnpm run build
- Commit + push + PR si nécessaire.
3) Le site “Proposer / Citer / ¶” (para-tools)
Où ça vit ?
-
src/layouts/EditionLayout.astroinjecte un script qui :- ajoute “¶” (lien d’ancre), “Citer”, “Proposer”
- construit l’URL de création d’issue Gitea
- embarque si possible le paragraphe exact (sinon un extrait)
-
src/components/ProposeModal.astrogère la modal 2 étapes :- Type (correction/fact-check)
- Category (cat/style, cat/lexique, etc.)
- ouvre ensuite l’issue en nouvel onglet sans quitter le site
Invariants (non négociables)
- Ancre + URL + Chemin doivent toujours être présents.
- Le mode “texte exact” est best effort :
- si trop long → fallback extrait + note
- priorité absolue : rester robuste et cliquable.
Limites / règles de taille
- FULL_TEXT_SOFT_LIMIT : taille max pour tenter d’embarquer “copie exacte”
- URL_HARD_LIMIT : si l’URL devient trop longue → repasse en extrait
But : éviter des issues amputées + éviter des URLs trop longues / fragiles.
4) Format des tickets (machine-readable)
Le parsing des tickets est fait par scripts/apply-ticket.mjs + workflow auto-label.
Donc le contenu doit rester “parsable”.
Sections attendues (au minimum) :
Chemin: /.../Ancre: #p-...Texte actuel (...)(idéalement “copie exacte”, sinon “extrait”)Proposition (remplacer par): ...Justification: ...(peut être vide, mais le champ doit exister si possible)
Voir aussi : docs/CONTRAT_TICKETS.md
5) Appliquer un ticket en local : apply-ticket
Commandes
-
Dry run (recommandé) :
node scripts/apply-ticket.mjs <N> --dry-run
-
Application réelle :
node scripts/apply-ticket.mjs <N>
Comportements de sûreté (guardrails)
-
--dry-run:- aucun fichier écrit
- aucun backup créé
- affiche BEFORE/AFTER (extrait)
-
Mode écriture :
- crée un backup
.bak.issue-<N>uniquement si écriture - match “best effort” mais refuse si score insuffisant
- crée un backup
Après application
git diff -- <fichier>git add <fichier>git commit -m "edit: apply ticket #N (...)"
6) Contrat de citabilité : ancres + churn test
Pourquoi ?
Les ancres sont le “socle de citabilité”. On veut prévenir les liens morts.
Scripts
-
npm run test:anchors- compare les ancres de
dist/avec une baseline - calcule le churn et signale les pages modifiées
- compare les ancres de
-
npm run test:anchors:update- met à jour la baseline (à faire seulement quand c’est volontaire)
Important :
dist/est un artefact ; la baseline sert à mesurer, pas à “éditer dist”.
7) Garde-fou JS inline : check-inline-js
Pourquoi : éviter qu’un JS inline cassé supprime les boutons et fasse disparaître “Proposer/Citer”.
node scripts/check-inline-js.mjs- intégré dans
npm test
8) CI (Gitea Actions)
Objectif
Sur chaque push/PR : vérifier automatiquement que :
- build OK
- ancres OK
- JS inline OK
Workflow
.gitea/workflows/ci.yml
Commande “contrat”
npm test- exécute : build + anchors + inline-js
9) ds220-runner (DS220+ / Gitea act-runner)
Comportement normal
Le runner lance des jobs dans des conteneurs éphémères qui démarrent/stop. DSM peut notifier “conteneur arrêté de manière inattendue” : c’est souvent un faux positif “bruyant”.
À surveiller vraiment
- Jobs en échec côté Gitea Actions
- logs mentionnant :
- auth API (401)
- labels manquants
- npm ci/build en échec
10) Dépannage (symptômes → causes fréquentes)
“Proposer” ouvre deux onglets / remplace l’onglet courant
Cause : double handler click / manque de stopPropagation / mauvais fallback.
Fix : le flux doit ouvrir nouvel onglet uniquement, et sinon prompt.
“Proposer/Citer/¶” disparaissent
Cause : JS inline cassé → exception ou erreur syntaxe.
Fix : node scripts/check-inline-js.mjs + vérifier dist/.../index.html console.
apply-ticket : “Proposition introuvable”
Cause : ticket sans section “Proposition (remplacer par):”. Fix : respecter le contrat de ticket.
apply-ticket : “Match trop faible”
Cause : texte actuel absent / trop tronqué / mismatch. Fix :
- privilégier “Texte actuel (copie exacte du paragraphe)”
- sinon le script récupère via
dist(si possible).
11) Règles de contribution (discipline de repo)
- Toute modif éditoriale passe par ticket → apply-ticket → tests.
- Toute modif structurelle (layouts, rendu, MDX) doit être suivie de :
npm test- éventuellement
npm run test:anchors:updatesi changement volontaire d’ancres.
- Ne jamais éditer
dist/à la main.
12) Commandes utiles (raccourcis)
- Dev :
npm run dev - Build :
npm run build - Tests :
npm test - Anchors :
npm run test:anchors - Apply ticket :
node scripts/apply-ticket.mjs <N> --dry-run