Bertrand Florat Tech articles Others articles Projects Cours et papiers CV Contact

Comment faire de bons ADR (décisions d'architecture) ?

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.

Autres resources

Liens : liste des templates d'ADR courants