Ustagammon/docs/adr/0001-consigner-les-decisions-dans-des-adr.md

0001. Consigner les décisions dans des ADR

• Statut : accepté
• Date : 2026-11-02
• Décideurs : Pierre

Contexte

Les premières décisions du projet étaient consignées dans un fichier unique, docs/decisions.md, à côté des plans et de la feuille de route. Or ces documents n'ont pas la même durée de vie : un plan ou une ligne de feuille de route est temporaire et disparaî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 l'historique. Les mélanger rend les choix plus difficiles à retrouver et à remettre en cause proprement.

Décision

Chaque décision structurante fait l'objet d'un ADR (Architecture Decision Record) : un fichier docs/adr/NNNN-titre-court.md, numéroté dans l'ordre, au format de docs/adr/modele.md. 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 ». L'index docs/adr/README.md liste tous les ADR.

Les plans (docs/plans/) et la feuille de route ne contiennent que le travail à faire ; un plan réalisé est supprimé, et ce qu'il contenait de durable passe dans un ADR, dans la description de la merge request ou dans le journal.

docs/decisions.md est supprimé ; ses entrées deviennent les ADR 0002 à 0006.

Alternatives écartées

• Garder docs/decisions.md : un seul fichier qui grossit, où l'on ne distingue pas une décision en vigueur d'une décision remplacée.
• Ne garder la trace que dans les merge requests : elle existe déjà là, mais hors du dépôt, sur un serveur qui peut changer.

Conséquences

• make test vérifie la forme des ADR (numérotation, statut, sections, index).
• Les ADR 0002 à 0006 reprennent des décisions antérieures à celui-ci, avec leur date d'origine.

Amendements

2026-11-02 — Amender plutôt que multiplier les ADR

Décidé par Pierre, pour ne pas créer un ADR à chaque précision. Un ADR accepté peut recevoir un amendement : une section « Amendements » en fin de fichier, une sous-section datée par amendement, qui dit qui l'a décidé, ce qu'il change et pourquoi. Le texte d'origine n'est pas réécrit ; s'il le faut, une courte mention renvoie à l'amendement. Un nouvel ADR (qui fait passer l'ancien au statut « remplacé par NNNN ») reste nécessaire quand la décision elle-même est abandonnée au profit d'une autre.