ADR : Garder une trace et comprendre les choix techniques

J’ai eu l’opportunité de présenter ce sujet lors d’un événement organisé par l’association /dev/var à Toulon. Cet échange avec des professionnels passionnés a permis de mettre en lumière les avantages des Architecture Decision Records et leur utilité dans la gestion des choix techniques.

Lorsque vous héritez d’un projet, il peut être difficile de comprendre pourquoi certains choix techniques ont été faits. Cette confusion peut ralentir la prise en main et compliquer l’évolution du projet. Les Architecture Decision Records (ADR) offrent une solution simple : documenter les choix architecturaux et les raisons derrière chaque décision.

Dans cet article, découvrez en détail ce que sont les ADR, leur utilité, et comment les intégrer à votre workflow.

Qu’est-ce qu’un ADR?

Un Architecture Decision Record est une courte documentation qui :

• Explique une décision architecturale prise dans un projet.
• Fournit le contexte historique et les raisons de cette décision.
• Mentionne les alternatives envisagées, y compris celles rejetées.
• Aide à comprendre pourquoi une solution qui semble sous-optimale aujourd’hui était pertinente dans son contexte initial.

Chaque ADR est unique et suit un format simple :

• Un fichier texte court, versionnable (idéalement stocké dans un dépôt Git ou un outil comme Jira).
• Un ID unique pour chaque décision, facilitant la recherche.
• Un cycle de vie clair avec des statuts : Proposed, Accepted, Rejected, ou Superseded.

Exemple d’ADR minimaliste :

ADR-001: Choisir PostgreSQL comme base de données
Status: Accepted
Context: Nous avons besoin d’une base relationnelle pour gérer des transactions complexes.
Decision: Utiliser PostgreSQL pour sa robustesse et ses fonctionnalités avancées.
Consequences: Nécessite des compétences PostgreSQL dans l’équipe.

Pourquoi adopter les ADR?

Les ADR permettent de résoudre plusieurs problématiques fréquentes dans les projets :

• Suivre l’historique des choix techniques et comprendre le contexte dans lequel ils ont été pris.
• Éviter les débats inutiles en documentant les alternatives déjà étudiées.
• Préparer les nouveaux membres de l’équipe avec une documentation claire et accessible.
• Améliorer la collaboration inter-équipes en centralisant les décisions dans un format standardisé.

Les différents types de documentation technique

Avant de plonger dans les ADR, il est utile de comprendre les types de documentation que l’on peut rencontrer, classés selon deux axes :

• Build / Run : documentations utiles pour construire ou maintenir un système.
• Théorie / Pratique : documentations explicatives ou directement applicables.

Voici un aperçu des principales catégories :

• Tutoriels : guides pas à pas pour apprendre à faire quelque chose.
• How-to : recettes spécifiques à un problème donné.
• Explications : documentation conceptuelle pour comprendre une technologie ou un choix.
• Références : documentation exhaustive (API, manuels).

Les ADR se situent entre la pratique et la théorie, comblant le fossé entre documentation explicative et historique.

Comment créer et gérer les ADR?

1. Structure d’un ADR

Un ADR suit une structure standard :

• Titre et ID : identifier clairement la décision.
• Contexte : décrire les besoins et contraintes.
• Décision : expliquer le choix retenu.
• Conséquences : préciser l’impact du choix.

2. Cycle de vie

Un ADR peut passer par plusieurs statuts :

• Proposed : la décision est en discussion.
• Accepted : la décision est validée et mise en œuvre.
• Rejected : la décision est écartée pour une autre solution.
• Superseded : la décision est remplacée par une nouvelle.

Une proposed peut être soit accepted soit refused. Une accepted peut passer en superseded.

On a donc de cette facon l’historique complet ainsi que les décision

3. Où les stocker?

• Dépôt Git : stocker les ADR avec le code pour garantir leur accessibilité.
• Outils collaboratifs : Jira, Confluence ou tout outil de gestion documentaire.

Les outils pour gérer les ADR

Un outil comme adr-tools simplifie grandement la gestion des ADR. Il permet :

• De générer automatiquement des fichiers ADR avec un ID unique.
• De maintenir une table des matières à jour.
• De créer un graphe illustrant les relations entre les différentes décisions.

Exemple de commande adr-tools

adr new "Choisir React pour le frontend"

Cela génère un fichier prêt à être complété, avec un ID unique et une structure standard.

Conclusion

Adopter les ADR, c’est investir dans une documentation pérenne qui fait le lien entre les choix techniques passés et l’avenir du projet. Les ADR ne se contentent pas de lister des décisions : ils expliquent pourquoi un choix a été fait, même si ce choix semble aujourd’hui discutable. En tenant compte du contexte historique, vous facilitez le travail des équipes présentes et futures.

N’attendez pas que vos projets deviennent un casse-tête de Kapla en équilibre précaire : adoptez les ADR dès aujourd’hui !

Vous pouvez les utiliser en dehors du contexte technique pour justifier des choix opérationnel par exemple.

Voici les slides de la présentation