207 lines
6.6 KiB
Markdown
207 lines
6.6 KiB
Markdown
# 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”)
|
||
1) Sur le site, cliquer **Proposer** sur un paragraphe.
|
||
2) Choisir Type (Correction / Fact-check), puis Category.
|
||
3) Gitea ouvre un ticket pré-rempli (Chemin/URL/Ancre + texte actuel).
|
||
4) Rédiger la **Proposition (remplacer par)** + Justification.
|
||
5) En local :
|
||
- `node scripts/apply-ticket.mjs <num>` (d’abord `--dry-run`)
|
||
- `npm run test:anchors`
|
||
- `npm run build`
|
||
6) Commit + push + PR si nécessaire.
|
||
|
||
---
|
||
|
||
## 3) Le site “Proposer / Citer / ¶” (para-tools)
|
||
### Où ça vit ?
|
||
- `src/layouts/EditionLayout.astro` injecte 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.astro` gè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
|
||
|
||
### 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
|
||
|
||
- `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:update` si 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`
|