ravenous_roll20/docs/development.md

107 lines
4.0 KiB
Markdown

# Développer et publier Ravenous Roll20
Ce guide regroupe les commandes avancées retirées du README. Les contrats de
comportement et d'architecture restent respectivement dans
[`FEATURES.md`](../FEATURES.md) et [`ARCHITECTURE.md`](../ARCHITECTURE.md).
## Construction
Prérequis : Git, Python 3.11 ou plus récent et `uv`. Depuis la racine :
```sh
git submodule update --init --recursive
./scripts/build.sh
```
Le build écrit la feuille, les métadonnées et les fixtures déterministes dans
`build/`. Il lit notamment `ravenous_typst/data/src/character_sheet.yaml`, les
écoles TSV, les origines YAML, les glossaires et
`ravenous_typst/data/config/build.yaml`. Les modèles maintenus à la main sont
dans `src/`; ne modifiez pas directement `build/`.
## Thèmes
Les palettes viennent de `ravenous_typst/setup/theme/themes.typ`. Le thème
initial vient de `document.color_scheme` dans la configuration du livre.
```sh
./scripts/build.sh --list-themes
./scripts/build.sh --theme-ui steel --output-dir build-steel
./scripts/build.sh --theme-ui steel --output-dir build-steel --check
```
Tous les thèmes restent sélectionnables par personnage, quel que soit le thème
initial du bundle.
## Vérification complète
```sh
./scripts/build.sh
uv run python -m unittest discover -s tests -v
node tests/test_worker.mjs
node tests/test_mod_import.mjs
node tests/test_character_io.mjs
node tests/test_craft_import.mjs
node tests/test_effects_import.mjs
node tests/test_shared_effects.mjs
uv run python -m unittest discover -s craft_web/tests -v
uv run python -m unittest discover -s effects_web/tests -v
./scripts/run-python-coverage.sh
./scripts/build.sh --check
uv run python craft_web/tools/build.py --check
uv run python effects_web/tools/build.py --check
```
La couverture mesure les générateurs Python, écrit des fichiers ignorés dans
`coverage/` et impose le seuil de lignes de 85 % défini dans `.coveragerc`.
`./scripts/test-worker-container.sh` peut exécuter le test du worker dans un
conteneur Podman isolé après le build. Aucun de ces tests ne remplace une
validation dans Roll20.
## Mettre à jour les données du livre
```sh
git submodule update --remote ravenous_typst
./scripts/build.sh
```
Contrôlez le diff du sous-module et les descriptions traduites avant de valider
la mise à jour. La limite des tiers d'école et les trigrammes proviennent de la
configuration épinglée ; ne les recopiez pas dans les modèles.
## CI, badges et publication
Jenkins initialise les sous-modules, prépare `uv` et SQLite, construit les trois
livrables, exécute les tests, impose la couverture, archive les résultats et
vérifie les builds déterministes.
Les badges `version.svg`, `test.svg` et `coverage.svg` sont finalisés même après
un échec, archivés seuls avec empreintes et publiés uniquement depuis `main`
dans `/mnt/assets/coverage/Ravenous/ravenous_roll20/main/`. Ils sont servis à :
- `https://assets.dandaedre.com/coverage/Ravenous/ravenous_roll20/main/version.svg` ;
- `https://assets.dandaedre.com/coverage/Ravenous/ravenous_roll20/main/test.svg` ;
- `https://assets.dandaedre.com/coverage/Ravenous/ravenous_roll20/main/coverage.svg`.
Le moteur SVG est copié depuis `agent-tasks` à la révision
`fb9d8f7d16f100c2d1377f23394a2302eac9ab18`. Le serveur d'actifs devrait monter
les fichiers en lecture seule, désactiver le listing, appliquer une CSP
restrictive aux SVG et revalider rapidement ces URL mutables.
Les branches de publication des trois produits sont :
- `main` et `master` : noms de production ;
- `candlelight` : suffixe `_candlelight` ;
- `lighthouse` : suffixe `_lighthouse` ;
- les autres branches : construction et archivage sans déploiement.
Les cibles de production sont :
- `/mnt/assets/ravenous_roll20/ravenous_sheet/` ;
- `/mnt/assets/ravenous_roll20/ravenous_craft/` ;
- `/mnt/assets/ravenous_roll20/ravenous_effects/`.
Chaque aide de déploiement vérifie une liste blanche et utilise `rsync --delete`
uniquement dans le sous-dossier du produit. Les détails de flux et de sécurité
sont dans [`ARCHITECTURE.md`](../ARCHITECTURE.md#ci-and-deployment-topology).