Décisions en ADR ; plans et feuille de route temporaires #2

2026-11-02T12:23:51Z

pierre commented

2026-11-02 12:23:51 +00:00

Pourquoi

Jusqu'ici, les décisions du projet étaient consignées dans un fichier unique, docs/decisions.md, rangé au même niveau que les plans des tâches déléguées et la feuille de route. Pierre a relevé que ces documents n'ont pas la même nature : un plan ou une ligne de feuille de route décrit du travail à faire et n'a plus d'intérêt une fois réalisé, alors qu'une décision doit rester lisible tant qu'elle s'applique, et même après, pour comprendre pourquoi le projet est comme il est. Les mélanger rend les choix plus difficiles à retrouver, et ne dit pas si une décision est toujours en vigueur ou si elle a été remplacée.

Concrètement, le plan de l'étude du moteur (MR !1) contenait à la fois des consignes de travail, devenues inutiles, et l'argumentaire du choix du moteur, qui doit rester.

Deuxième point, signalé par Pierre : les hash de commit étaient écrits entre backticks dans les documents, ce qui empêche Gitea d'en faire des liens.

Quoi

Les décisions deviennent des ADR (Architecture Decision Records), un fichier par décision dans docs/adr/, avec un index (docs/adr/README.md) et un modèle (docs/adr/modele.md). Les cinq entrées de docs/decisions.md deviennent les ADR 0002 à 0006, avec leur date d'origine. L'ADR 0001 consigne la règle elle-même. docs/decisions.md est supprimé.
Plans et feuille de route deviennent temporaires. Un plan est supprimé quand sa tâche est close ; une ligne de feuille de route réalisée est retirée. Le plan de l'étude du moteur est supprimé : son contenu durable (versions étudiées, tableau comparatif, preuves recoupées, fichiers à reprendre, plan d'isolement, risques) est intégralement dans l'ADR 0005. Le modèle de plan passe dans docs/plans/README.md.
Un nouveau test, tests/test_adr.sh, lancé par make test, vérifie la forme des ADR : numérotation continue, titre conforme au numéro, statut et date valides, sections obligatoires, présence dans l'index.
Hash de commit sans backticks dans tous les documents. La règle est ajoutée aux consignes des MR dans docs/organisation.md, avec une autre contrainte du serveur : pas d'émojis dans les titres et descriptions.
CLAUDE.md, docs/organisation.md, docs/etape-0.md, la feuille de route et le journal renvoient désormais aux ADR.

Comment

Un ADR suit le format courant : statut, date, décideurs, puis contexte, décision, alternatives écartées et conséquences. Un ADR accepté n'est plus réécrit : une décision qui change donne un nouvel ADR, et l'ancien passe au statut « remplacé par NNNN ». C'est ce qui permet de lire l'historique des choix sans fouiller git.

docs/organisation.md distingue maintenant explicitement les documents durables (cadrage, ADR, journal, merge requests) des documents temporaires (feuille de route, spécification d'étape, plans), et impose de reporter le contenu durable d'un plan avant de le supprimer.

Le test des ADR a été vérifié dans les deux sens : il passe sur les ADR actuels, et il échoue sur une copie volontairement abîmée (statut invalide, trou dans la numérotation, titre incorrect, ADR absent de l'index), avec un message clair pour chaque problème.

Choix et compromis

Le journal reste. Il n'est pas un document de décision : il trace les sessions, y compris les incidents, et il est durable par nature. Ses anciennes mentions de docs/decisions.md sont laissées telles quelles, puisqu'elles décrivent ce qui était vrai ce jour-là.
Les ADR 0002 à 0006 sont rédigés après coup. Leurs dates sont celles des décisions d'origine, pas celle de leur rédaction. L'ADR 0002 (le nom) n'a pas d'alternatives documentées, puisque le choix a été fait avant le démarrage technique : c'est dit tel quel.
Une spécification d'étape (docs/etape-0.md) est elle aussi considérée comme temporaire et sera supprimée à la fin de l'étape, ce qu'elle a de durable passant en ADR. C'est une extension de la demande de Pierre, cohérente avec elle.

Risques et déploiement

Seuls de la documentation et un test changent. Le seul risque est que make test échoue à l'avenir sur un ADR mal formé : c'est le but recherché.

Retour arrière : annuler le commit de fusion ; docs/decisions.md et le plan supprimé reviennent avec lui.

Comment vérifier

git switch main && git pull
make lint && make test
less docs/adr/README.md
less docs/adr/0005-moteur-gnubg-officiel.md

Pour voir le test des ADR échouer, modifier le statut d'un ADR en « peut-être », lancer make test, puis annuler la modification avec git checkout docs/adr.

Hors périmètre

La MR !1 apparaît encore « open » dans Gitea, alors que sa fusion a bien eu lieu côté git : le commit de fusion 6958acc est sur main, sur le serveur comme en local. La cause n'est pas établie. La base de données du serveur refuse déjà les caractères sur 4 octets (erreur MySQL 1366 sur un émoji à la création de cette même MR), ce qui oriente vers un problème de jeu de caractères. À examiner dans les journaux de Gitea, hors de ce dépôt.

Generated with Claude Code https://claude.com/claude-code

## Pourquoi Jusqu'ici, les décisions du projet étaient consignées dans un fichier unique, `docs/decisions.md`, rangé au même niveau que les plans des tâches déléguées et la feuille de route. Pierre a relevé que ces documents n'ont pas la même nature : un plan ou une ligne de feuille de route décrit du travail à faire et n'a plus d'intérêt une fois réalisé, alors qu'une décision doit rester lisible tant qu'elle s'applique, et même après, pour comprendre pourquoi le projet est comme il est. Les mélanger rend les choix plus difficiles à retrouver, et ne dit pas si une décision est toujours en vigueur ou si elle a été remplacée. Concrètement, le plan de l'étude du moteur (MR !1) contenait à la fois des consignes de travail, devenues inutiles, et l'argumentaire du choix du moteur, qui doit rester. Deuxième point, signalé par Pierre : les hash de commit étaient écrits entre backticks dans les documents, ce qui empêche Gitea d'en faire des liens. ## Quoi - **Les décisions deviennent des ADR** (Architecture Decision Records), un fichier par décision dans `docs/adr/`, avec un index (`docs/adr/README.md`) et un modèle (`docs/adr/modele.md`). Les cinq entrées de `docs/decisions.md` deviennent les ADR 0002 à 0006, avec leur date d'origine. L'ADR 0001 consigne la règle elle-même. `docs/decisions.md` est supprimé. - **Plans et feuille de route deviennent temporaires.** Un plan est supprimé quand sa tâche est close ; une ligne de feuille de route réalisée est retirée. Le plan de l'étude du moteur est supprimé : son contenu durable (versions étudiées, tableau comparatif, preuves recoupées, fichiers à reprendre, plan d'isolement, risques) est intégralement dans l'ADR 0005. Le modèle de plan passe dans `docs/plans/README.md`. - **Un nouveau test**, `tests/test_adr.sh`, lancé par `make test`, vérifie la forme des ADR : numérotation continue, titre conforme au numéro, statut et date valides, sections obligatoires, présence dans l'index. - **Hash de commit sans backticks** dans tous les documents. La règle est ajoutée aux consignes des MR dans `docs/organisation.md`, avec une autre contrainte du serveur : pas d'émojis dans les titres et descriptions. - `CLAUDE.md`, `docs/organisation.md`, `docs/etape-0.md`, la feuille de route et le journal renvoient désormais aux ADR. ## Comment Un ADR suit le format courant : statut, date, décideurs, puis contexte, décision, alternatives écartées et conséquences. Un ADR accepté n'est plus réécrit : une décision qui change donne un nouvel ADR, et l'ancien passe au statut « remplacé par NNNN ». C'est ce qui permet de lire l'historique des choix sans fouiller git. `docs/organisation.md` distingue maintenant explicitement les documents durables (cadrage, ADR, journal, merge requests) des documents temporaires (feuille de route, spécification d'étape, plans), et impose de reporter le contenu durable d'un plan avant de le supprimer. Le test des ADR a été vérifié dans les deux sens : il passe sur les ADR actuels, et il échoue sur une copie volontairement abîmée (statut invalide, trou dans la numérotation, titre incorrect, ADR absent de l'index), avec un message clair pour chaque problème. ## Choix et compromis - **Le journal reste.** Il n'est pas un document de décision : il trace les sessions, y compris les incidents, et il est durable par nature. Ses anciennes mentions de `docs/decisions.md` sont laissées telles quelles, puisqu'elles décrivent ce qui était vrai ce jour-là. - **Les ADR 0002 à 0006 sont rédigés après coup.** Leurs dates sont celles des décisions d'origine, pas celle de leur rédaction. L'ADR 0002 (le nom) n'a pas d'alternatives documentées, puisque le choix a été fait avant le démarrage technique : c'est dit tel quel. - **Une spécification d'étape (`docs/etape-0.md`) est elle aussi considérée comme temporaire** et sera supprimée à la fin de l'étape, ce qu'elle a de durable passant en ADR. C'est une extension de la demande de Pierre, cohérente avec elle. ## Risques et déploiement Seuls de la documentation et un test changent. Le seul risque est que `make test` échoue à l'avenir sur un ADR mal formé : c'est le but recherché. Retour arrière : annuler le commit de fusion ; `docs/decisions.md` et le plan supprimé reviennent avec lui. ## Comment vérifier ``` git switch main && git pull make lint && make test less docs/adr/README.md less docs/adr/0005-moteur-gnubg-officiel.md ``` Pour voir le test des ADR échouer, modifier le statut d'un ADR en « peut-être », lancer `make test`, puis annuler la modification avec `git checkout docs/adr`. ## Hors périmètre - **La MR !1 apparaît encore « open » dans Gitea**, alors que sa fusion a bien eu lieu côté git : le commit de fusion 6958acc est sur `main`, sur le serveur comme en local. La cause n'est pas établie. La base de données du serveur refuse déjà les caractères sur 4 octets (erreur MySQL 1366 sur un émoji à la création de cette même MR), ce qui oriente vers un problème de jeu de caractères. À examiner dans les journaux de Gitea, hors de ce dépôt. Generated with Claude Code https://claude.com/claude-code

pierre added 1 commit 2026-11-02 12:23:51 +00:00

Décisions en ADR ; plans et feuille de route temporaires d017f3338b

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

pierre referenced this pull request

2026-11-02 12:41:37 +00:00

ADR 0007 : architecture et conventions de code #3

pierre manually merged commit aa4f504123 into main

2026-11-02 18:01:24 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: pierre/Ustagammon#2