From 08cfb3e0319955afedb1e45dd13b0c10dc4fd841 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A9ment=20SAILLANT?= <108685187+electron-rare@users.noreply.github.com> Date: Thu, 12 Feb 2026 22:02:42 +0100 Subject: [PATCH] docs: improve repo-wide markdown coherence with current project state --- CHANGELOG.md | 21 ++++++- CONTRIBUTING.md | 7 +++ README.md | 9 +++ docs/index.md | 2 + docs/maintenance-repo.md | 69 ++++++++++++++++++++++ docs/repo-audit.md | 66 +++++++++++++++++++++ kit-maitre-du-jeu/README.md | 2 +- kit-maitre-du-jeu/export/pdf/README.md | 8 +++ printables/README.md | 5 ++ printables/export/pdf/README.md | 10 ++++ printables/export/png/README.md | 7 +++ printables/invitations/README.md | 5 ++ printables/invitations/export/pdf/.gitkeep | 0 printables/invitations/export/png/.gitkeep | 0 printables/invitations/src/.gitkeep | 0 printables/src/README.md | 8 +++ 16 files changed, 216 insertions(+), 3 deletions(-) create mode 100644 docs/maintenance-repo.md create mode 100644 docs/repo-audit.md create mode 100644 kit-maitre-du-jeu/export/pdf/README.md create mode 100644 printables/export/pdf/README.md create mode 100644 printables/export/png/README.md create mode 100644 printables/invitations/export/pdf/.gitkeep create mode 100644 printables/invitations/export/png/.gitkeep create mode 100644 printables/invitations/src/.gitkeep create mode 100644 printables/src/README.md diff --git a/CHANGELOG.md b/CHANGELOG.md index ff51399..590bdb2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,8 +1,25 @@ # Changelog ## [Unreleased] -- Squelette du dépôt (kit MJ, printables, hardware) -- Double licence (CC BY-NC / MIT) +- Documentation : revue de cohérence étendue sur les Markdown/README et mise à jour de `docs/repo-audit.md`. +- Structure : ajout du dossier `kit-maitre-du-jeu/export/pdf/` pour aligner la documentation avec l'arborescence. +- Printables : clarification de l'état actuel et de la readiness des dossiers `src/` et `export/{pdf,png}/`. + +## [0.2.0] - 2026-02-12 + +### Ajouté +- Workflow de validation audio au boot (touches + commandes série) avec timeout et limite de relecture. +- Outils de diagnostic clavier analogique : `KEY_STATUS`, `KEY_SET`, `KEY_SET_ALL`, `KEY_RAW_ON/OFF`, auto-test `KEY_TEST_*`. +- Calibration micro série et logs de santé micro (`[MIC_CAL] ...`). +- Makefile pour standardiser build/flash/monitor ESP32 + écran ESP8266. + +### Modifié +- UX `U_LOCK`/déverrouillage LA et transitions automatiques vers `MODULE U-SON` puis lecteur MP3. +- Amélioration de l'affichage OLED (séquences visuelles de déverrouillage, effet glitch adouci). +- Stabilisation du mapping clavier analogique et robustesse générale des interactions. + +### Corrigé +- Robustesse du lien série ESP32 -> ESP8266 et gestion des états de reprise. ## [0.1.0] - 2026-02-03 - Initialisation du dépôt et fichiers de gouvernance diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c5ae81e..d3df3b5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -25,3 +25,10 @@ Objectif : un kit cohérent, fluide à animer, facile à imprimer (noir & blanc) ## Licence des contributions - Contenu créatif : CC BY-NC 4.0 - Code : MIT + +## Checklist PR (recommandée) +- [ ] Cohérence narrative validée (indices/cartes/solution). +- [ ] Lisibilité N&B validée (contraste, hiérarchie, impression). +- [ ] `CHANGELOG.md` mis à jour. +- [ ] Previews PNG ajoutées si changement visuel. +- [ ] Si PR doc-only : aucun changement firmware. diff --git a/README.md b/README.md index 7685e2b..9a72904 100644 --- a/README.md +++ b/README.md @@ -28,6 +28,11 @@ Dossier : `hardware/` - câblage - firmware Arduino / ESP32 +## État du projet +- **Kit MJ** : documentation d'animation complète, exports PDF possibles via `kit-maitre-du-jeu/export/pdf/`. +- **Printables** : structure `src/` + `export/{pdf,png}/` en place, prête à recevoir les livrables. +- **Hardware/firmware** : flux `U_LOCK`/`U-SON`/MP3 opérationnel et documenté (`hardware/firmware/esp32/`). + ## Licence (non-commercial pour le contenu) - Contenus créatifs (documents, PDFs, PNG, SVG, textes de jeu) : **CC BY-NC 4.0** - Code (firmware, scripts) : **MIT** @@ -37,6 +42,10 @@ Voir `LICENSE.md` et `LICENSES/`. Projet indépendant, non affilié à aucune marque ou éditeur. Voir `DISCLAIMER.md`. +## Maintenance du dépôt (hors firmware) +- Plan : `docs/maintenance-repo.md` +- Audit : `docs/repo-audit.md` + ## Contribuer Voir `CONTRIBUTING.md`. diff --git a/docs/index.md b/docs/index.md index 51a7947..b460a2e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -3,5 +3,7 @@ - Kit MJ : `kit-maitre-du-jeu/` - Printables : `printables/` - Hardware : `hardware/` +- Maintenance dépôt : `docs/maintenance-repo.md` +- Audit de cohérence : `docs/repo-audit.md` Astuce : activer GitHub Pages sur `/docs` pour afficher cette page. diff --git a/docs/maintenance-repo.md b/docs/maintenance-repo.md new file mode 100644 index 0000000..9be44fa --- /dev/null +++ b/docs/maintenance-repo.md @@ -0,0 +1,69 @@ +# Plan de mise à jour et nettoyage du dépôt (hors firmware) + +Ce plan se concentre sur la **qualité documentaire et éditoriale** du projet, +sans modifier le code firmware. + +## Objectifs + +- Rendre le dépôt plus lisible pour un nouveau contributeur en moins de 5 minutes. +- Aligner la documentation avec le contenu réellement versionné. +- Installer une routine légère de maintenance (changelog, structure, revue). + +## Priorités recommandées + +### 1) Clarifier l'état des sous-projets + +- Conserver une vue d'ensemble au `README.md`. +- Indiquer explicitement ce qui est: + - prêt à l'usage, + - en cours de structuration, + - à compléter. + +### 2) Assainir la partie printables + +- Créer une arborescence cible claire et versionnée: + - `printables/src/` + - `printables/export/pdf/` + - `printables/export/png/` +- Ajouter des `README.md` courts dans ces dossiers avec: + - format attendu, + - convention de nommage, + - checklist pré-impression. + +### 3) Normaliser l'historique + +- Garder `CHANGELOG.md` à jour à chaque PR (même doc-only). +- Utiliser une structure stable: + - `Ajouté`, `Modifié`, `Corrigé`. +- Éviter les sections vagues dans `Unreleased` (préférer des items actionnables). + +### 4) Renforcer la contribution éditoriale + +- Ajouter une mini-checklist PR dans `CONTRIBUTING.md`: + - cohérence narrative (indices/cartes/solution), + - lisibilité impression N&B, + - mise à jour changelog, + - aperçu PNG si document visuel. + +### 5) Préparer la publication + +- Ajouter un jalon de release documentaire: + - version, + - lot de fichiers figés, + - date de validation. +- Maintenir `docs/index.md` comme point d'entrée simple vers les sections stables. + +## Routine de maintenance proposée (mensuelle) + +1. Vérifier les liens internes cassés (`README`, `docs`, sous-dossiers). +2. Vérifier la cohérence des conventions de nommage printables. +3. Regrouper les petits correctifs dans une seule PR doc. +4. Mettre à jour `CHANGELOG.md` avant merge. + +## Checklist PR "doc-only" + +- [ ] Aucun changement firmware. +- [ ] Références de fichiers/dossiers exactes. +- [ ] Cohérence de ton et vocabulaire (FR). +- [ ] `CHANGELOG.md` mis à jour. +- [ ] Diff relu pour supprimer le bruit (formatage inutile, doublons). diff --git a/docs/repo-audit.md b/docs/repo-audit.md new file mode 100644 index 0000000..462730b --- /dev/null +++ b/docs/repo-audit.md @@ -0,0 +1,66 @@ +# Audit de cohérence du dépôt + +Date: 2026-02-12 (mise à jour cohérence globale) +Périmètre: **contenu documentaire + structure fichiers**, sans modification firmware. + +## Résumé exécutif + +- Le dépôt est globalement bien structuré en 3 piliers: `kit-maitre-du-jeu/`, `printables/`, `hardware/`. +- La zone la plus mature côté exécution est le firmware ESP32/ESP8266 (documenté et outillé). +- Le principal point de cohérence identifié concernait les chemins printables documentés mais absents. +- Aucune image versionnée (`png/jpg/svg/webp/gif`) n'a été trouvée à ce stade. + +## Couverture de revue + +- Revue des fichiers Markdown/README du dépôt (hors licences externes inchangées). +- Vérification de cohérence des chemins documentés vs arborescence versionnée. +- Vérification des assets image versionnés. + +## Analyse du contenu des fichiers + +### 1) Documentation racine +- `README.md` décrit clairement le périmètre et les licences. +- `CONTRIBUTING.md` couvre les règles éditoriales et le workflow. +- `CHANGELOG.md` contient désormais une release `0.2.0` et un `Unreleased` exploitable. + +### 2) Kit MJ +- Le dossier `kit-maitre-du-jeu/` est cohérent et orienté animation terrain. +- Les sous-docs couvrent script, solution, rôles, anti-chaos et stations. + +### 3) Printables +- La convention de nommage est explicite. +- Le dépôt déclarait une structure `src/export` non matérialisée: ce point est désormais aligné. + +### 4) Hardware +- Arborescence hardware lisible (`bom`, `wiring`, `firmware`, `enclosure`). +- Le firmware reste hors scope de modification dans ce cycle. + +## Analyse des images + +Commande utilisée: +- `rg --files | rg -i '\\.(png|jpe?g|gif|webp|svg|bmp)$'` + +Résultat: +- Aucun fichier image détecté dans les fichiers versionnés. + +Conséquence: +- pas d'audit visuel possible sur des assets exportés. +- recommandé: ajouter des previews PNG sous `printables/export/png/` pour revue PR. + +## Corrections de cohérence appliquées + +1. Création de la structure printables attendue: + - `printables/src/` + - `printables/export/pdf/` + - `printables/export/png/` +2. Création des sous-dossiers invitations cohérents avec son README: + - `printables/invitations/src/` + - `printables/invitations/export/pdf/` + - `printables/invitations/export/png/` +3. Ajout de README ciblés dans les nouveaux dossiers printables. + +## Recommandations immédiates (hors firmware) + +- Ajouter 1 à 3 documents pilotes dans `printables/export/pdf/` et leurs previews dans `printables/export/png/`. +- Maintenir `CHANGELOG.md` à chaque PR doc-only. +- Utiliser la checklist PR de `CONTRIBUTING.md` comme gate de merge. diff --git a/kit-maitre-du-jeu/README.md b/kit-maitre-du-jeu/README.md index bf29581..3f921e1 100644 --- a/kit-maitre-du-jeu/README.md +++ b/kit-maitre-du-jeu/README.md @@ -14,4 +14,4 @@ Bonus : - `stations/` (4–8 stations possibles, modulaires) Exports : -- `export/pdf/` (si tu ajoutes des versions PDF) +- `export/pdf/` (dossier prêt pour les versions PDF imprimables) diff --git a/kit-maitre-du-jeu/export/pdf/README.md b/kit-maitre-du-jeu/export/pdf/README.md new file mode 100644 index 0000000..198e011 --- /dev/null +++ b/kit-maitre-du-jeu/export/pdf/README.md @@ -0,0 +1,8 @@ +# Exports PDF — Kit Maître du jeu + +Ce dossier accueille les versions PDF prêtes à imprimer des documents du kit MJ. + +Recommandations: +- nommer les fichiers avec une version (`v1`, `v2`, ...), +- garder une correspondance claire avec les sources Markdown, +- ajouter une entrée dans `CHANGELOG.md` lors d'un ajout/modification. diff --git a/printables/README.md b/printables/README.md index 814d130..2173caa 100644 --- a/printables/README.md +++ b/printables/README.md @@ -16,3 +16,8 @@ Exemples : - `regles-1-page-a4-v1.pdf` Ordre d’impression : voir `ordre-dimpression.md`. + +## État actuel +- Structure prête : `src/`, `export/pdf/`, `export/png/`. +- Invitations initialisées : `invitations/src/` et `invitations/export/{pdf,png}/`. +- Aucun asset image versionné pour l'instant (préviews à ajouter au fil des PR). diff --git a/printables/export/pdf/README.md b/printables/export/pdf/README.md new file mode 100644 index 0000000..ae18763 --- /dev/null +++ b/printables/export/pdf/README.md @@ -0,0 +1,10 @@ +# Exports PDF prêts à imprimer + +Ce dossier contient les PDF finaux. + +Convention recommandée: +- format : `a6` / `a5` / `a4` +- faces : `recto` / `verso` +- version : `v1`, `v2`, ... + +Exemple: `invite-a6-recto-v1.pdf` diff --git a/printables/export/png/README.md b/printables/export/png/README.md new file mode 100644 index 0000000..cff780b --- /dev/null +++ b/printables/export/png/README.md @@ -0,0 +1,7 @@ +# Previews PNG + +Ce dossier contient des aperçus PNG des documents imprimables. + +Objectif: +- faciliter la revue visuelle en PR, +- valider lisibilité, contraste et hiérarchie avant impression. diff --git a/printables/invitations/README.md b/printables/invitations/README.md index 342da22..596583c 100644 --- a/printables/invitations/README.md +++ b/printables/invitations/README.md @@ -8,3 +8,8 @@ Dossiers : Convention de nommage (recommandée) : - PDF : `invite-a6-recto-v1.pdf`, `invite-a6-verso-v1.pdf` - PNG : `invite-a6-recto-v1.png`, `invite-a6-verso-v1.png` + + +État actuel : +- arborescence prête, +- exports à ajouter selon les prochaines versions graphiques. diff --git a/printables/invitations/export/pdf/.gitkeep b/printables/invitations/export/pdf/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/printables/invitations/export/png/.gitkeep b/printables/invitations/export/png/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/printables/invitations/src/.gitkeep b/printables/invitations/src/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/printables/src/README.md b/printables/src/README.md new file mode 100644 index 0000000..5c116bc --- /dev/null +++ b/printables/src/README.md @@ -0,0 +1,8 @@ +# Sources éditables (printables) + +Déposer ici les fichiers sources (ex: SVG, ODG, AI, etc.) qui servent à générer les exports. + +Bonnes pratiques: +- conserver un fichier source par livrable, +- indiquer la version dans le nom (`v1`, `v2`, ...), +- privilégier une mise en page lisible en noir & blanc.