From 77ca5a60cad3db080e649820338e7199208035b3 Mon Sep 17 00:00:00 2001 From: Pierre MARTIN Date: Mon, 2 Nov 2026 13:45:34 +0100 Subject: [PATCH] =?UTF-8?q?ADR=200008=20:=20glossaire=20et=20sc=C3=A9nario?= =?UTF-8?q?s,=20source=20unique=20pour=20le=20code,=20l'aide=20et=20les=20?= =?UTF-8?q?tests?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 1 + ...08-glossaire-et-scenarios-source-unique.md | 82 +++++++++++++++++++ docs/adr/README.md | 1 + docs/feuille-de-route.md | 2 +- docs/glossaire/README.md | 60 ++++++++++++++ docs/glossaire/backgammon.md | 9 ++ docs/glossaire/barre.md | 9 ++ docs/glossaire/blot.md | 9 ++ docs/glossaire/branche.md | 9 ++ docs/glossaire/compte-de-points.md | 9 ++ docs/glossaire/coup.md | 9 ++ docs/glossaire/course.md | 9 ++ docs/glossaire/doubler.md | 9 ++ docs/glossaire/equite.md | 9 ++ docs/glossaire/evenement-de-partie.md | 9 ++ docs/glossaire/gammon.md | 9 ++ docs/glossaire/identifiant-de-match.md | 9 ++ docs/glossaire/identifiant-de-position.md | 9 ++ docs/glossaire/jet.md | 9 ++ docs/glossaire/match.md | 9 ++ docs/glossaire/moteur.md | 9 ++ docs/glossaire/partie.md | 9 ++ docs/glossaire/passer.md | 9 ++ docs/glossaire/pion.md | 7 ++ docs/glossaire/pli.md | 9 ++ docs/glossaire/point.md | 9 ++ docs/glossaire/prendre.md | 9 ++ docs/glossaire/regle-de-crawford.md | 9 ++ docs/glossaire/regle-de-jacoby.md | 9 ++ docs/glossaire/sortie.md | 9 ++ docs/glossaire/videau.md | 9 ++ docs/organisation.md | 2 + docs/scenarios/README.md | 30 +++++++ docs/scenarios/jouer-une-partie.feature.md | 48 +++++++++++ tests/test_glossary.sh | 36 ++++++++ tests/test_scenarios.sh | 25 ++++++ 36 files changed, 518 insertions(+), 1 deletion(-) create mode 100644 docs/adr/0008-glossaire-et-scenarios-source-unique.md create mode 100644 docs/glossaire/README.md create mode 100644 docs/glossaire/backgammon.md create mode 100644 docs/glossaire/barre.md create mode 100644 docs/glossaire/blot.md create mode 100644 docs/glossaire/branche.md create mode 100644 docs/glossaire/compte-de-points.md create mode 100644 docs/glossaire/coup.md create mode 100644 docs/glossaire/course.md create mode 100644 docs/glossaire/doubler.md create mode 100644 docs/glossaire/equite.md create mode 100644 docs/glossaire/evenement-de-partie.md create mode 100644 docs/glossaire/gammon.md create mode 100644 docs/glossaire/identifiant-de-match.md create mode 100644 docs/glossaire/identifiant-de-position.md create mode 100644 docs/glossaire/jet.md create mode 100644 docs/glossaire/match.md create mode 100644 docs/glossaire/moteur.md create mode 100644 docs/glossaire/partie.md create mode 100644 docs/glossaire/passer.md create mode 100644 docs/glossaire/pion.md create mode 100644 docs/glossaire/pli.md create mode 100644 docs/glossaire/point.md create mode 100644 docs/glossaire/prendre.md create mode 100644 docs/glossaire/regle-de-crawford.md create mode 100644 docs/glossaire/regle-de-jacoby.md create mode 100644 docs/glossaire/sortie.md create mode 100644 docs/glossaire/videau.md create mode 100644 docs/scenarios/README.md create mode 100644 docs/scenarios/jouer-une-partie.feature.md create mode 100755 tests/test_glossary.sh create mode 100755 tests/test_scenarios.sh diff --git a/CLAUDE.md b/CLAUDE.md index b1bbcfa..a069b06 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -16,6 +16,7 @@ est la feuille de route. - **Licence** : tout le code sous GPLv3. Les contenus pédagogiques (leçons, textes) sous CC BY-SA 4.0. - **Langue** : interface, contenus, commentaires de code et messages de commit en français ; identifiants du code en anglais. - **Architecture et code** : simplicité d'abord, pas de sur-ingénierie ; domaine pur, moteur derrière `engine.h`, parties en journal d'événements ; règles complètes dans l'ADR 0007, à transmettre à chaque sous-agent. +- **Glossaire et aide** : chaque terme du jeu a sa fiche dans `docs/glossaire/` (traduction anglaise = nom dans le code) ; chaque fonction visible a son scénario dans `docs/scenarios/`, à la fois aide de l'app et test de bout en bout. Une seule source, jamais dupliquée (ADR 0008). - **Communauté de départ** : l'app sera d'abord diffusée auprès des joueurs de l'Atelier du Huit, café associatif à Cugnaux. Elle doit être accessible à de vrais débutants. - **Identité visuelle** : définie par le brief créatif (https://claude.ai/artifact/36WMwZWqvMxXvSSVBJTgwd). Les choix de produit, de ton et d'identité appartiennent au porteur du projet ; le rôle de Claude Code est technique : les mettre en œuvre et signaler leurs conséquences techniques. diff --git a/docs/adr/0008-glossaire-et-scenarios-source-unique.md b/docs/adr/0008-glossaire-et-scenarios-source-unique.md new file mode 100644 index 0000000..a712daa --- /dev/null +++ b/docs/adr/0008-glossaire-et-scenarios-source-unique.md @@ -0,0 +1,82 @@ +# 0008. Glossaire et scénarios : une source unique pour le code, l'aide et les tests + +- **Statut** : accepté +- **Date** : 2026-11-02 +- **Décideurs** : Pierre, sur proposition de Claude Code pour le format + +## Contexte + +Le code est en anglais (ADR 0007), l'interface et la documentation en +français. Il faut un lien explicite entre les deux langues pour que le code +reste compréhensible et que les mots du jeu soient les mêmes partout. Le +cadrage prévoit aussi un glossaire dans l'application (« chaque terme technique +est touchable »). + +Pierre veut une documentation utilisateur fondée sur des cas d'usage réels, +orientée tâches, versionnée avec le code, consultable dans l'application, et +utilisable comme base des tests de bout en bout. Il impose une seule source de +vérité : aucune documentation dupliquée. + +## Décision + +**Glossaire : `docs/glossaire/`, un fichier par terme.** + +- Chaque fichier (`videau.md`, `equite.md`…) commence par un en-tête qui donne + le terme français, sa traduction anglaise (le nom utilisé dans le code) et, le + cas échéant, le type du domaine qui l'implémente : + + ``` + --- + term: Videau + english: Cube + code: Cube + --- + ``` + +- Puis un titre, une ligne « **En bref** : » (une phrase, celle que l'app + affiche quand on touche le terme), et des détails facultatifs. +- Dans le code, chaque type du domaine qui correspond à un terme porte en + commentaire le chemin de sa fiche (`Glossaire : docs/glossaire/videau.md`). +- Des tests vérifient la forme des fiches, l'unicité des traductions anglaises, + l'index, et, dès que le domaine existe, le lien dans les deux sens : chaque + `code:` désigne un type existant, chaque référence du code désigne une fiche + existante. + +**Documentation utilisateur : `docs/scenarios/`, des scénarios métier.** + +- Un fichier par tâche réelle de l'utilisateur (« Jouer une partie contre + l'ordinateur », « Comprendre mon erreur »…), écrit pour un joueur, en + français, à la deuxième personne, avec des étapes concrètes. +- Le format est du Markdown avec Gherkin (fichiers `.feature.md`, pris en + charge par Cucumber) : le même fichier se lit comme une page d'aide et + s'exécute comme test de bout en bout. Les étapes s'écrivent en français + (« Étant donné », « Quand », « Alors »). +- L'outil qui exécute ces scénarios est choisi avec le socle (PWA ou Android). + D'ici là, les scénarios sont déroulés à la main et servent de guide de test. + +**Une seule source.** L'application n'a pas sa propre copie de l'aide ni du +glossaire : le build les copie depuis `docs/glossaire/` et `docs/scenarios/` +vers les ressources de l'application. Ces copies ne sont jamais commitées. La +documentation affichée est donc toujours celle de la version installée. + +## Alternatives écartées + +- **Un seul fichier de glossaire** : plus difficile à lier depuis le code et + depuis l'application (une fiche = un lien), et des conflits de fusion + fréquents. +- **Documentation utilisateur rédigée à part des tests** : deux textes qui + divergent tôt ou tard. +- **Gherkin classique (`.feature`)** : exécutable, mais austère comme page + d'aide. Le Markdown avec Gherkin donne les deux. +- **Aide intégrée en dur dans l'application** : une seconde source à + maintenir. + +## Conséquences + +- Les textes du glossaire et des scénarios sont des contenus pédagogiques, sous + CC BY-SA 4.0. Leur ton relève de Pierre : les fiches rédigées par Claude Code + sont marquées « à relire » jusqu'à sa relecture. +- Tout nouveau type du domaine qui correspond à un mot du jeu demande sa fiche + de glossaire dans la même merge request. +- Toute fonction visible par l'utilisateur demande son scénario dans la même + merge request. diff --git a/docs/adr/README.md b/docs/adr/README.md index d129e34..e9fcaa3 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -13,3 +13,4 @@ passe au statut « remplacé par NNNN ». Voir l'ADR 0001. | [0005](0005-moteur-gnubg-officiel.md) | Source du moteur : GNU Backgammon officiel, commit 14b6798 | accepté | | [0006](0006-merge-requests-systematiques.md) | Merge requests systématiques, fusionnées par Claude Code | accepté | | [0007](0007-architecture-et-conventions-de-code.md) | Architecture et conventions de code | accepté | +| [0008](0008-glossaire-et-scenarios-source-unique.md) | Glossaire et scénarios : une source unique pour le code, l'aide et les tests | accepté | diff --git a/docs/feuille-de-route.md b/docs/feuille-de-route.md index 331ca27..33b8118 100644 --- a/docs/feuille-de-route.md +++ b/docs/feuille-de-route.md @@ -21,7 +21,7 @@ Acquis : socle du dépôt, organisation (ADR 0001, 0003, 0006), source du moteur | Mesures | Pierre relève les mesures sur le Fairphone 4 | ⏳ | | | Décision | Socle PWA ou Android natif, consigné dans un ADR — validation de Pierre | ⏳ | | | 0c | Android natif (NDK, Gradle en ligne de commande, `make deploy` via adb) | ⏸ si 0b échoue | | -| 0d | Plateau minimal jouable sur le socle retenu | ⏳ | | +| 0d | Plateau minimal jouable sur le socle retenu ; vérifié avec Pierre en suivant `docs/scenarios/jouer-une-partie.feature.md` | ⏳ | | **Critère de fin** : une partie complète jouée sur le Fairphone 4, moins de 2 s par coup de l'IA en niveau standard, tous les tests au vert. diff --git a/docs/glossaire/README.md b/docs/glossaire/README.md new file mode 100644 index 0000000..6bc6998 --- /dev/null +++ b/docs/glossaire/README.md @@ -0,0 +1,60 @@ +# Glossaire + +Les mots du jeu, une fiche par terme, avec leur traduction anglaise utilisée +dans le code (ADR 0008). Ces fiches sont la seule source : l'application les +affiche telles quelles quand on touche un terme. + +Fiches rédigées par Claude Code, **à relire** par Pierre (contenu pédagogique, +CC BY-SA 4.0). + +## Format d'une fiche + +``` +--- +term: Videau +english: Cube +code: Cube +--- +# Videau + +**En bref** : une phrase, celle qu'affiche l'application. + +Détails facultatifs. + +Voir aussi : [Doubler](doubler.md) +``` + +`code` est facultatif : il désigne le type du domaine qui implémente le terme, +dès qu'il existe. Dans le code, ce type porte en commentaire le chemin de sa +fiche (`Glossaire : docs/glossaire/videau.md`). + +## Termes + +| Terme | Anglais (code) | +| --- | --- | +| [Backgammon](backgammon.md) | Backgammon | +| [Barre](barre.md) | Bar | +| [Blot](blot.md) | Blot | +| [Branche](branche.md) | Branch | +| [Compte de points](compte-de-points.md) | Pip count | +| [Coup](coup.md) | Move | +| [Course](course.md) | Race | +| [Doubler](doubler.md) | Double | +| [Équité](equite.md) | Equity | +| [Événement de partie](evenement-de-partie.md) | Game event | +| [Gammon](gammon.md) | Gammon | +| [Identifiant de match](identifiant-de-match.md) | Match ID | +| [Identifiant de position](identifiant-de-position.md) | Position ID | +| [Jet](jet.md) | Roll | +| [Match](match.md) | Match | +| [Moteur](moteur.md) | Engine | +| [Partie](partie.md) | Game | +| [Passer](passer.md) | Drop | +| [Pion](pion.md) | Checker | +| [Pli](pli.md) | Ply | +| [Point](point.md) | Point | +| [Prendre](prendre.md) | Take | +| [Règle de Crawford](regle-de-crawford.md) | Crawford rule | +| [Règle de Jacoby](regle-de-jacoby.md) | Jacoby rule | +| [Sortie](sortie.md) | Bear-off | +| [Videau](videau.md) | Cube | diff --git a/docs/glossaire/backgammon.md b/docs/glossaire/backgammon.md new file mode 100644 index 0000000..6d1dcfa --- /dev/null +++ b/docs/glossaire/backgammon.md @@ -0,0 +1,9 @@ +--- +term: Backgammon +english: Backgammon +--- +# Backgammon + +**En bref** : victoire triple : l'adversaire n'a sorti aucun pion et en a encore sur la barre ou dans votre dernier quart du plateau. + +Voir aussi : [Gammon](gammon.md) diff --git a/docs/glossaire/barre.md b/docs/glossaire/barre.md new file mode 100644 index 0000000..634d3b1 --- /dev/null +++ b/docs/glossaire/barre.md @@ -0,0 +1,9 @@ +--- +term: Barre +english: Bar +--- +# Barre + +**En bref** : bande centrale du plateau où vont les pions frappés ; un joueur doit y faire rentrer ses pions avant de jouer les autres. + +Voir aussi : [Blot](blot.md) diff --git a/docs/glossaire/blot.md b/docs/glossaire/blot.md new file mode 100644 index 0000000..611f4f3 --- /dev/null +++ b/docs/glossaire/blot.md @@ -0,0 +1,9 @@ +--- +term: Blot +english: Blot +--- +# Blot + +**En bref** : pion seul sur un point : l'adversaire peut le frapper et l'envoyer sur la barre. + +Voir aussi : [Point](point.md), [Barre](barre.md) diff --git a/docs/glossaire/branche.md b/docs/glossaire/branche.md new file mode 100644 index 0000000..11f0e33 --- /dev/null +++ b/docs/glossaire/branche.md @@ -0,0 +1,9 @@ +--- +term: Branche +english: Branch +--- +# Branche + +**En bref** : suite de coups rejouée à partir d'un moment d'une partie (« Rejouer d'ici ») ; la partie d'origine reste intacte. + +Voir aussi : [Événement de partie](evenement-de-partie.md) diff --git a/docs/glossaire/compte-de-points.md b/docs/glossaire/compte-de-points.md new file mode 100644 index 0000000..5aa1912 --- /dev/null +++ b/docs/glossaire/compte-de-points.md @@ -0,0 +1,9 @@ +--- +term: Compte de points +english: Pip count +--- +# Compte de points + +**En bref** : nombre total de cases que vos pions doivent encore parcourir pour tous sortir ; le plus petit compte est en avance dans la course. + +Voir aussi : [Course](course.md) diff --git a/docs/glossaire/coup.md b/docs/glossaire/coup.md new file mode 100644 index 0000000..c1272f3 --- /dev/null +++ b/docs/glossaire/coup.md @@ -0,0 +1,9 @@ +--- +term: Coup +english: Move +--- +# Coup + +**En bref** : le déplacement complet des pions pour un jet, noté par exemple 8/5 6/5 : un pion de la case 8 à la case 5, un autre de la case 6 à la case 5. + +Voir aussi : [Jet](jet.md) diff --git a/docs/glossaire/course.md b/docs/glossaire/course.md new file mode 100644 index 0000000..b13f1a4 --- /dev/null +++ b/docs/glossaire/course.md @@ -0,0 +1,9 @@ +--- +term: Course +english: Race +--- +# Course + +**En bref** : position où les pions des deux joueurs se sont croisés : plus aucun contact n'est possible, c'est au plus rapide. + +Voir aussi : [Compte de points](compte-de-points.md), [Sortie](sortie.md) diff --git a/docs/glossaire/doubler.md b/docs/glossaire/doubler.md new file mode 100644 index 0000000..cd7c181 --- /dev/null +++ b/docs/glossaire/doubler.md @@ -0,0 +1,9 @@ +--- +term: Doubler +english: Double +--- +# Doubler + +**En bref** : proposer à l'adversaire, avant de lancer les dés, de doubler la valeur de la partie ; il peut prendre ou passer. + +Voir aussi : [Videau](videau.md) diff --git a/docs/glossaire/equite.md b/docs/glossaire/equite.md new file mode 100644 index 0000000..dfe5217 --- /dev/null +++ b/docs/glossaire/equite.md @@ -0,0 +1,9 @@ +--- +term: Équité +english: Equity +--- +# Équité + +**En bref** : ce que vaut une position selon le moteur, en points gagnés ou perdus en moyenne : +1 pour une victoire simple assurée, −1 pour une défaite simple assurée. + +Voir aussi : [Moteur](moteur.md), [Pli](pli.md) diff --git a/docs/glossaire/evenement-de-partie.md b/docs/glossaire/evenement-de-partie.md new file mode 100644 index 0000000..7a5c77e --- /dev/null +++ b/docs/glossaire/evenement-de-partie.md @@ -0,0 +1,9 @@ +--- +term: Événement de partie +english: Game event +--- +# Événement de partie + +**En bref** : ce qui s'est passé à un moment de la partie : un jet, un coup, un double… ; une partie est la suite de ses événements. + +Voir aussi : [Branche](branche.md), [Partie](partie.md) diff --git a/docs/glossaire/gammon.md b/docs/glossaire/gammon.md new file mode 100644 index 0000000..24eced9 --- /dev/null +++ b/docs/glossaire/gammon.md @@ -0,0 +1,9 @@ +--- +term: Gammon +english: Gammon +--- +# Gammon + +**En bref** : victoire double : l'adversaire n'a sorti aucun pion quand vous avez sorti tous les vôtres. + +Voir aussi : [Backgammon](backgammon.md) diff --git a/docs/glossaire/identifiant-de-match.md b/docs/glossaire/identifiant-de-match.md new file mode 100644 index 0000000..e97efc9 --- /dev/null +++ b/docs/glossaire/identifiant-de-match.md @@ -0,0 +1,9 @@ +--- +term: Identifiant de match +english: Match ID +--- +# Identifiant de match + +**En bref** : code de 12 caractères qui décrit le reste de l'état du jeu : score, videau, joueur au trait, dés ; c'est le format de GNU Backgammon. + +Voir aussi : [Identifiant de position](identifiant-de-position.md) diff --git a/docs/glossaire/identifiant-de-position.md b/docs/glossaire/identifiant-de-position.md new file mode 100644 index 0000000..7ea8165 --- /dev/null +++ b/docs/glossaire/identifiant-de-position.md @@ -0,0 +1,9 @@ +--- +term: Identifiant de position +english: Position ID +--- +# Identifiant de position + +**En bref** : code de 14 caractères, par exemple 4HPwATDgc/ABMA, qui décrit la place de tous les pions ; c'est le format de GNU Backgammon. + +Voir aussi : [Identifiant de match](identifiant-de-match.md) diff --git a/docs/glossaire/jet.md b/docs/glossaire/jet.md new file mode 100644 index 0000000..1ec2bcf --- /dev/null +++ b/docs/glossaire/jet.md @@ -0,0 +1,9 @@ +--- +term: Jet +english: Roll +--- +# Jet + +**En bref** : le lancer des deux dés ; un double (deux dés identiques) se joue quatre fois. + +Voir aussi : [Coup](coup.md) diff --git a/docs/glossaire/match.md b/docs/glossaire/match.md new file mode 100644 index 0000000..bcd35da --- /dev/null +++ b/docs/glossaire/match.md @@ -0,0 +1,9 @@ +--- +term: Match +english: Match +--- +# Match + +**En bref** : suite de parties jouée jusqu'à ce qu'un joueur atteigne un nombre de points fixé à l'avance, par exemple 5 points. + +Voir aussi : [Partie](partie.md), [Règle de Crawford](regle-de-crawford.md) diff --git a/docs/glossaire/moteur.md b/docs/glossaire/moteur.md new file mode 100644 index 0000000..05c292b --- /dev/null +++ b/docs/glossaire/moteur.md @@ -0,0 +1,9 @@ +--- +term: Moteur +english: Engine +--- +# Moteur + +**En bref** : GNU Backgammon, le programme qui calcule les coups, le videau et les évaluations ; Ustagammon ne décide jamais rien sans lui. + +Voir aussi : [Équité](equite.md), [Pli](pli.md) diff --git a/docs/glossaire/partie.md b/docs/glossaire/partie.md new file mode 100644 index 0000000..a8bb813 --- /dev/null +++ b/docs/glossaire/partie.md @@ -0,0 +1,9 @@ +--- +term: Partie +english: Game +--- +# Partie + +**En bref** : une partie se joue jusqu'à ce qu'un joueur ait sorti tous ses pions ; elle rapporte 1, 2 ou 3 points, multipliés par la valeur du videau. + +Voir aussi : [Match](match.md), [Gammon](gammon.md), [Videau](videau.md) diff --git a/docs/glossaire/passer.md b/docs/glossaire/passer.md new file mode 100644 index 0000000..0c76a3d --- /dev/null +++ b/docs/glossaire/passer.md @@ -0,0 +1,9 @@ +--- +term: Passer +english: Drop +--- +# Passer + +**En bref** : refuser un double : vous abandonnez la partie et perdez sa valeur d'avant le double. + +Voir aussi : [Prendre](prendre.md), [Videau](videau.md) diff --git a/docs/glossaire/pion.md b/docs/glossaire/pion.md new file mode 100644 index 0000000..727508b --- /dev/null +++ b/docs/glossaire/pion.md @@ -0,0 +1,7 @@ +--- +term: Pion +english: Checker +--- +# Pion + +**En bref** : chacun des 15 jetons d'un joueur. diff --git a/docs/glossaire/pli.md b/docs/glossaire/pli.md new file mode 100644 index 0000000..f6e0125 --- /dev/null +++ b/docs/glossaire/pli.md @@ -0,0 +1,9 @@ +--- +term: Pli +english: Ply +--- +# Pli + +**En bref** : profondeur de calcul du moteur : à 0 pli il juge la position telle quelle, à 2 plis il examine aussi les jets suivants des deux joueurs ; plus de plis, c'est plus fort et plus lent. + +Voir aussi : [Moteur](moteur.md) diff --git a/docs/glossaire/point.md b/docs/glossaire/point.md new file mode 100644 index 0000000..1caf0a3 --- /dev/null +++ b/docs/glossaire/point.md @@ -0,0 +1,9 @@ +--- +term: Point +english: Point +--- +# Point + +**En bref** : chacune des 24 flèches du plateau ; un point est « fait » quand au moins deux de vos pions l'occupent, et l'adversaire ne peut plus s'y poser. + +Voir aussi : [Blot](blot.md) diff --git a/docs/glossaire/prendre.md b/docs/glossaire/prendre.md new file mode 100644 index 0000000..a9aab12 --- /dev/null +++ b/docs/glossaire/prendre.md @@ -0,0 +1,9 @@ +--- +term: Prendre +english: Take +--- +# Prendre + +**En bref** : accepter un double : la partie continue à valeur doublée, et vous possédez le videau, vous seul pourrez redoubler. + +Voir aussi : [Passer](passer.md), [Videau](videau.md) diff --git a/docs/glossaire/regle-de-crawford.md b/docs/glossaire/regle-de-crawford.md new file mode 100644 index 0000000..e551882 --- /dev/null +++ b/docs/glossaire/regle-de-crawford.md @@ -0,0 +1,9 @@ +--- +term: Règle de Crawford +english: Crawford rule +--- +# Règle de Crawford + +**En bref** : en match, dans la partie qui suit le moment où un joueur arrive à un point de la victoire, personne ne peut doubler. + +Voir aussi : [Match](match.md), [Doubler](doubler.md) diff --git a/docs/glossaire/regle-de-jacoby.md b/docs/glossaire/regle-de-jacoby.md new file mode 100644 index 0000000..8d081c6 --- /dev/null +++ b/docs/glossaire/regle-de-jacoby.md @@ -0,0 +1,9 @@ +--- +term: Règle de Jacoby +english: Jacoby rule +--- +# Règle de Jacoby + +**En bref** : en partie libre, hors match, un gammon ou un backgammon ne compte que si le videau a été utilisé. + +Voir aussi : [Gammon](gammon.md), [Videau](videau.md) diff --git a/docs/glossaire/sortie.md b/docs/glossaire/sortie.md new file mode 100644 index 0000000..95d679a --- /dev/null +++ b/docs/glossaire/sortie.md @@ -0,0 +1,9 @@ +--- +term: Sortie +english: Bear-off +--- +# Sortie + +**En bref** : dernière phase : quand tous ses pions sont dans son dernier quart du plateau, un joueur peut les retirer du jeu ; le premier à tout sortir gagne. + +Voir aussi : [Course](course.md) diff --git a/docs/glossaire/videau.md b/docs/glossaire/videau.md new file mode 100644 index 0000000..1d24b72 --- /dev/null +++ b/docs/glossaire/videau.md @@ -0,0 +1,9 @@ +--- +term: Videau +english: Cube +--- +# Videau + +**En bref** : le dé à doubler, marqué 2, 4, 8, 16, 32 et 64 : il indique la valeur actuelle de la partie. + +Voir aussi : [Doubler](doubler.md), [Prendre](prendre.md), [Passer](passer.md) diff --git a/docs/organisation.md b/docs/organisation.md index 95dca5d..466f1b4 100644 --- a/docs/organisation.md +++ b/docs/organisation.md @@ -29,6 +29,8 @@ Deux familles de documents, de durée de vie différente (ADR 0001). | `docs/cadrage.md` | Vision, périmètre, architecture cible | Quand Pierre change le cadrage | | `docs/adr/` | Un ADR par décision structurante ; index dans `docs/adr/README.md` | À chaque décision ; jamais réécrit une fois accepté | | `docs/journal.md` | Une entrée datée par session : fait, décidé, suite | En fin de session | +| `docs/glossaire/` | Une fiche par terme du jeu, avec sa traduction anglaise utilisée dans le code (ADR 0008) | Avec chaque nouveau terme du domaine | +| `docs/scenarios/` | Documentation utilisateur en scénarios, aussi tests de bout en bout (ADR 0008) | Avec chaque fonction visible | | Merge requests (git.sans.pub) | Le détail de chaque changement : pourquoi, comment, vérification | À chaque changement | **Temporaires** : ils décrivent le travail à faire et disparaissent une fois diff --git a/docs/scenarios/README.md b/docs/scenarios/README.md new file mode 100644 index 0000000..054d1bf --- /dev/null +++ b/docs/scenarios/README.md @@ -0,0 +1,30 @@ +# Scénarios d'utilisation + +La documentation utilisateur d'Ustagammon : un fichier par tâche réelle d'un +joueur, écrit pour lui. Ces fichiers sont la seule source (ADR 0008) : +l'application les affiche comme pages d'aide, et ils servent de tests de bout +en bout. + +Tant que l'outil d'exécution n'est pas choisi (avec le socle, fin de +l'étape 0), les scénarios se déroulent à la main : ils servent alors de guide +de test. + +## Format + +Markdown avec Gherkin (`.feature.md`), étapes en français : + +- `# Fonctionnalité : `, puis un court paragraphe qui explique à quoi + elle sert, pour le joueur ; +- `## Scénario : ` ; +- des étapes en liste : `* Étant donné …`, `* Quand …`, `* Et …`, `* Alors …`. + +Règles d'écriture : la deuxième personne (« vous »), les mots du glossaire +(`docs/glossaire/`), des étapes que le joueur peut faire et vérifier lui-même, +pas de détail technique. La syntaxe exacte sera validée avec l'outil +d'exécution. + +## Scénarios + +| Fichier | Tâche | Depuis | +| --- | --- | --- | +| [jouer-une-partie.feature.md](jouer-une-partie.feature.md) | Jouer une partie contre l'ordinateur | Étape 0d | diff --git a/docs/scenarios/jouer-une-partie.feature.md b/docs/scenarios/jouer-une-partie.feature.md new file mode 100644 index 0000000..9d8abea --- /dev/null +++ b/docs/scenarios/jouer-une-partie.feature.md @@ -0,0 +1,48 @@ +# Fonctionnalité : Jouer une partie contre l'ordinateur + +Vous jouez une partie complète contre l'ordinateur, qui s'appuie sur le moteur +GNU Backgammon. L'application tire les dés, vous propose uniquement des coups +permis par les règles, et l'ordinateur joue et décide du videau tout seul. + +## Scénario : Commencer une partie + +* Étant donné que vous avez ouvert Ustagammon +* Quand vous touchez « Nouvelle partie » +* Alors le plateau s'affiche avec les pions en position de départ +* Et le premier jet de dés désigne qui commence + +## Scénario : Jouer votre coup + +* Étant donné que c'est à vous de jouer et que les dés sont tirés +* Quand vous touchez un pion puis la case où vous voulez l'amener +* Alors le pion s'y déplace si ce déplacement est permis par les dés +* Et un déplacement interdit est refusé sans changer le plateau +* Quand vous avez utilisé vos dés +* Alors votre coup est validé et c'est au tour de l'ordinateur + +## Scénario : L'ordinateur joue + +* Étant donné que c'est au tour de l'ordinateur +* Quand ses dés sont tirés +* Alors il joue son coup en moins de 2 secondes +* Et son coup s'affiche sur le plateau + +## Scénario : Prendre le double de l'ordinateur + +* Étant donné que l'ordinateur vous propose de doubler +* Quand vous touchez « Prendre » +* Alors la partie continue à valeur doublée +* Et le videau passe de votre côté : vous seul pourrez redoubler + +## Scénario : Passer le double de l'ordinateur + +* Étant donné que l'ordinateur vous propose de doubler +* Quand vous touchez « Passer » +* Alors la partie s'arrête +* Et vous perdez la partie à sa valeur d'avant le double + +## Scénario : Finir la partie + +* Étant donné qu'un joueur a sorti tous ses pions +* Alors la partie s'arrête +* Et le résultat indique le gagnant et les points gagnés : simple, gammon ou backgammon, multipliés par le videau diff --git a/tests/test_glossary.sh b/tests/test_glossary.sh new file mode 100755 index 0000000..43168c7 --- /dev/null +++ b/tests/test_glossary.sh @@ -0,0 +1,36 @@ +#!/usr/bin/env bash +# Vérifie les fiches du glossaire (docs/glossaire/, ADR 0008) : +# en-tête avec term et english, titre identique au terme, ligne « En bref », +# traductions anglaises uniques, chaque fiche présente dans l'index, +# liens « Voir aussi » vers des fiches existantes. + +set -euo pipefail +cd "$(dirname "$0")/../docs/glossaire" + +errors=0 +report() { + echo "$1" + errors=$((errors + 1)) +} + +for f in *.md; do + [ "$f" = README.md ] && continue + + [ "$(sed -n 1p "$f")" = "---" ] || report "$f : l'en-tête doit commencer par ---" + term="$(sed -n 's/^term: //p' "$f")" + english="$(sed -n 's/^english: //p' "$f")" + [ -n "$term" ] || report "$f : champ term absent" + [ -n "$english" ] || report "$f : champ english absent" + grep -qx "# $term" "$f" || report "$f : le titre doit être « # $term »" + grep -qE '^\*\*En bref\*\* : .+' "$f" || report "$f : ligne « **En bref** : » absente" + grep -qF "]($f)" README.md || report "$f : absent de l'index README.md" + + while IFS= read -r link; do + [ -f "$link" ] || report "$f : lien vers une fiche inexistante ($link)" + done < <(grep -oE '\]\([^)]+\.md\)' "$f" | sed -E 's/^\]\((.*)\)$/\1/' || true) +done + +duplicates="$(find . -name '*.md' ! -name README.md -exec sed -n 's/^english: //p' {} + | sort | uniq -d)" +[ -z "$duplicates" ] || report "traductions anglaises en double : $duplicates" + +[ "$errors" -eq 0 ] diff --git a/tests/test_scenarios.sh b/tests/test_scenarios.sh new file mode 100755 index 0000000..3c2ef2e --- /dev/null +++ b/tests/test_scenarios.sh @@ -0,0 +1,25 @@ +#!/usr/bin/env bash +# Vérifie la forme des scénarios d'utilisation (docs/scenarios/, ADR 0008) : +# un titre « Fonctionnalité », au moins un « Scénario », des étapes qui +# commencent par un mot-clé Gherkin français, chaque fichier dans l'index. + +set -euo pipefail +cd "$(dirname "$0")/../docs/scenarios" + +errors=0 +report() { + echo "$1" + errors=$((errors + 1)) +} + +for f in *.feature.md; do + head -n1 "$f" | grep -qE '^# Fonctionnalité : .+' \ + || report "$f : la première ligne doit être « # Fonctionnalité : … »" + grep -qE '^## Scénario : .+' "$f" || report "$f : aucun « ## Scénario : … »" + while IFS= read -r step; do + report "$f : étape sans mot-clé Gherkin : $step" + done < <(grep -E '^\* ' "$f" | grep -vE '^\* (Étant donné|Quand|Alors|Et|Mais) ' || true) + grep -qF "]($f)" README.md || report "$f : absent de l'index README.md" +done + +[ "$errors" -eq 0 ]