Comment faire de bons ADR (décisions d'architecture) ?
Bertrand Florat - May 6, 2020
Registre des décisions d'architecture
Un registre de décisions d'architecture sert à consigner les décisions importantes d'architecture (les ADR, Architecture Decision Record).
Le but est de permettre la connaissance et la compréhension des choix a posteriori et de partager les décisions. Le dossier d'architecture quant à lui ne reprend pas ces choix mais ne fait apparaître que la décision finale.
Il n'y a qu'un seul registre d'ADR par projet.
Format d'un ADR
Chaque ADR est constitué d'un fichier unique au format asciidoc avec ce
nom : [séquence XYZ démarrant à 001]-[decision].adoc.
Format de la décision : en minuscule sans espaces avec des tirets comme
séparateur. Exemple : 007-API-devant-bases-existantes-perennes.adoc.
Chaque ADR contient idéalement le contenu suivant (adaptable en fonction des besoins) :
1) Historique
- Donner le statut et l'historique des changements d'états
- Les statuts possibles sont :
TODO(à rédiger),WIP(Work In Progress),PROPOSE,REJETE,VALIDE,DEPRECIE,REMPLACE. - Si le statut est
VALIDE, détailler la date et les décideurs qui ont validé. - Si le statut est
REMPLACE, donner la référence de l'ADR à prendre en compte. - Ne jamais supprimer un ADR (le mettre en statut
DEPRECIE) et ne pas réutiliser l'ID d'un autre ADR du même module. - Mentionner l'éventuel ADR qui le remplace. Exemple:
Remplacé par l'ADR 002-...
2) Contexte
Présente les choix possibles, les problématiques, les forces en jeu (techniques, organisationnelles, réglementaires, financières, humaines ...). Donner les forces, faiblesses, opportunités et risques de chaque solution (voir méthode SWOT).
Note:
- Si un point est rédhibitoire, l'indiquer.
- Numéroter les solution pour y référer sans ambiguïté
- Pour les cas les plus simples, deux paragraphes avantages/inconvénients pour chaque solution peuvent suffire.
- Dans certains cas, l'ADR ne peut contenir qu'une seule solution, le but étant de documenter les raisons de cette architecture.
3) Décision
Donner la décision retenue (être affirmatif et rappeler le numéro de
solution retenue). Exemple:
Nous effectuerons les signatures de PDF au fil de l'eau (solution 1).
4) Conséquences
Donner les éventuelles conséquences de la décision en terme de mise en œuvre. Ne pas reprendre les forces, faiblesses des solutions mais plutôt les conséquences pratiques de la décision. Donner les actions permettant de réduire les éventuels risques induis par la solution.
Exemples :
* Il conviendra de prévoir des logs spécifiques pour le traitement
*
Le risque d'indisponibilité sera couvert par des astreintes renforcées
Format du registre
Idéalement, un registre d'ADR propose un rendu visuel de tous les ADR avec leur statut et leur historique respectifs de façon à disposer d'une vue globale sur la situation de chaque décision. Statuts et historiques ne doivent en aucun cas être dupliqués car implique une double maintenance qui a très peu de chance d'être faite correctement. Dans la plupart des cas, mieux vaut ne faire figurer ces informations que dans chaque ADR même si cela implique de les ouvrir un pas un. Une alternative est de classer les ADR dans des sous-répertoires par statut mais cela rend le parcours des ADR plus difficiles.
Si vous utilisez Asciidoc (ce que je recommande vivement), une astuce existe : l'inclusion de tags. L'idée est de laisser le statut et l'historique mais chaque ADR mais de les inclure dans un tableau pour former le registre. Exemple :
Dans 001-dedoublonnage-requetes.adoc :
## Statut
// tag::statut[]
`VALIDE`
// end::statut[]
## Historique
// tag::historique[]
Validé le 26 nov 2019 avec xyz
// end::historique[]
et dans le registre (README.adoc) :
.Table Liste et statuts des ADR RECE
[cols="2,1a,4a"]
|===
|ADR |Statut |Historique
|link:001-dedoublonnage-requetes.adoc[001-dedoublonnage-requetes]
|include::001-dedoublonnage-requetes.adoc[tags=statut]
|include::001-dedoublonnage-requetes.adoc[tags=historique]
|link:002-appels-synchrones.adoc[002-appels-synchrones]
|include::002-appels-synchrones.adoc[tags=statut]
|include::002-appels-synchrones.adoc[tags=historique]
...
|===
Exemple complet d'ADR
## Historique
Statut: `VALIDE`
* Validé par xyz le 28 janvier
* Proposé par z le 02/01/2020
## Contexte
<Présentation générale de la problématique>
# Solution 1: <description solution>
## Forces
- Limite l'utilisation du réseau
## Faiblesses
- Moins robustesse
## Opportunités
## Risques
- [rédhibitoire] Nécessite que la signature se fasse en synchrone ou en fil l'eau
# Solution 2: <description solution>
## Forces
## Faiblesses
## Opportunités
## Risques
## Décisions
La solution 2 est retenue
## Conséquences
- Vérifier la configuration des JVM pour utiliser un générateur d'aléas
Conseils d'utilisation
- Ne pas hésiter à ajouter des images/schémas... Penser à Mermaid et Plantuml.
- Ne pas horodater les modifications de l'ADR lui-même, c'est le rôle de l'outil de gestion de version (GIT). Utiliser des messages de commit explicites.
- Un bon ADR doit être :
- court ;
- clair ;
- pertinent (explique bien le contexte, les choix possibles et la décision retenue) ;
- accessible de tous (Wiki, Github..., pas de documents bureautique) ;
- tracé (changelog, commits Git, ...) ;
- transparent : s'il manque des éléments de décision, les mentionner.