Dans un projet de développement logiciel, les décisions architecturales jouent un rôle essentiel, surtout pour les projets à long terme et lorsque les équipes connaissent du turnover. En effet, ces décisions ont souvent des implications profondes sur l’évolution du système et sa maintenance.
C’est dans ce contexte que les Architecture Decision Records (ADR) prennent toute leur importance, en offrant un moyen de tracer et justifier ces choix techniques, afin de faciliter la compréhension et la continuité du projet, même avec de nouveaux arrivants.
Dans cet article, nous allons explorer ce que sont les ADR, leur importance dans un projet, et nous aborderons également le concept d’ADR as Code, une approche moderne pour gérer ces enregistrements de manière automatisée et intégrée dans le pipeline de développement.
Qu’est-ce qu’un Architecture Decision Record (ADR) ?
Un ADR est un document simple et concis qui capture une décision architecturale clé, ainsi que le contexte et les raisons qui ont motivé cette décision. Il s’agit d’une méthode de documentation légère qui permet à une équipe de développement de suivre les décisions structurantes qui impactent l’architecture d’une application.
Chaque ADR suit généralement une structure simple :
- Titre : La décision prise, exprimée de manière succincte.
- Contexte : Les raisons qui ont conduit à cette décision, notamment les contraintes, les exigences, ou les problèmes rencontrés.
- Décision : Le choix architectural qui a été fait.
- Conséquences : Les implications de cette décision, positives comme négatives, ainsi que les impacts potentiels sur le projet.
Exemple d’un ADR classique :
# ADR 1 : Choix d'un framework frontend
## Contexte
L'équipe doit choisir un framework pour le développement de l'interface utilisateur. Nous avons évalué plusieurs options, dont Angular, React et Vue.js. Le projet nécessite une forte intégration avec des services backend, des fonctionnalités avancées comme le routing et le support TypeScript.
## Décision
Nous avons décidé d'utiliser Angular pour ce projet en raison de sa maturité, de sa bonne intégration avec TypeScript, et de la disponibilité d'une communauté active.
## Conséquences
Cette décision implique que les développeurs devront être formés à Angular, et nous devrons surveiller la performance de l'application, car Angular peut entraîner des charges supplémentaires pour des applications légères.
Pourquoi utiliser les ADR ?
Les ADR permettent de :
- Garder une trace de l’historique des décisions : Les choix architecturaux évoluent souvent au fil du projet, mais il est crucial de comprendre pourquoi certaines décisions ont été prises à un moment donné.
- Faciliter la communication : Les nouveaux membres de l’équipe, ou ceux qui ne sont pas directement impliqués dans certaines décisions, peuvent rapidement comprendre les choix qui ont été faits.
- Documenter les compromis : Chaque décision architecturale implique des compromis, et les ADR permettent de les rendre explicites et compréhensibles pour tous.
- Améliorer la cohérence du projet : En centralisant les décisions architecturales dans un format structuré, il devient plus facile de maintenir la cohérence à travers les différentes phases du projet.
ADR as Code
L’approche ADR as Code consiste à gérer les ADR de manière automatisée et versionnée, en les intégrant directement dans le code source du projet, tout comme n’importe quel autre fichier de configuration ou documentation. Cette méthode s’appuie souvent sur un format texte simple (comme le Markdown) et tire parti du contrôle de version (Git) pour suivre les modifications et évolutions des décisions.
Avec ADR as Code, les décisions architecturales deviennent une partie intégrante du projet. Cela présente plusieurs avantages :
- Versioning: Les ADR peuvent évoluer avec le projet, et chaque modification est tracée dans le système de versioning.
- Automatisation : Il est possible de lier les ADR à des pipelines CI/CD pour vérifier la cohérence entre les décisions prises et l’implémentation du code.
- Documentation continue : Les ADR sont accessibles et modifiables par toute l’équipe, favorisant une documentation vivante et à jour.
Exemple de workflow avec ADR as Code
Imaginons un projet dans lequel les ADR sont gérés dans un répertoire dédié, par exemple docs/adr/. Chaque nouvelle décision est ajoutée sous forme de fichier Markdown :
project-root/
└── docs/
└── adr/
└── 0001-use-angular.md
└── 0002-use-graphql-for-api.mdChaque fichier suit le format classique d’un ADR mais est versionné comme le reste du code. Par exemple, un ADR sur le choix d’utiliser GraphQL pour l’API ressemblerait à ceci :
# ADR 2 : Utiliser GraphQL pour l'API
## Contexte
Nous devons concevoir une API pour notre nouvelle application. L'API sera utilisée par plusieurs interfaces, incluant une application mobile et un front-end web. Nous avons étudié les approches REST et GraphQL.
## Décision
Nous avons décidé d'opter pour GraphQL car il permet de mieux répondre aux besoins des différentes interfaces avec une flexibilité accrue et une réduction des requêtes redondantes.
## Conséquences
Nous allons devoir former l'équipe à GraphQL et ajuster nos pratiques de développement. Cela pourrait aussi compliquer la mise en cache des requêtes, et nous devrons étudier cette question plus en détail.Mettre en place ADR as Code dans un pipeline CI/CD
Il est possible d’intégrer des vérifications automatiques dans un pipeline CI/CD pour s’assurer que les décisions architecturales sont respectées par le code. Par exemple, un ADR qui impose l’utilisation de GraphQL pourrait être associé à des tests qui valident que toutes les requêtes de l’application passent bien par l’API GraphQL.
Cela peut se faire avec des scripts personnalisés ou des outils comme adr-tools qui permettent de créer, lister et gérer les ADR directement depuis la ligne de commande.
Exemple d’implémentation avec adr-tools
Pour installer et utiliser adr-tools (MacOS et Linux), voici les étapes :
- Installez l’outil
brew install adr-tools2. Initialisez un nouveau répertoire ADR dans votre projet
adr init docs/adr3. Créez une nouvelle décision
adr new "Use GraphQL for API"Cela générera automatiquement un fichier Markdown avec une structure pré-remplie que vous pourrez compléter et versionner.
Conclusion
Les ADR sont un excellent moyen de structurer et de documenter les décisions architecturales d’un projet logiciel, assurant ainsi la clarté et la traçabilité des choix techniques. L’approche ADR as Code pousse encore plus loin cette idée en intégrant ces décisions directement dans le cycle de développement, avec des outils de versioning et d’automatisation.
Cette pratique renforce la transparence et la communication au sein des équipes tout en garantissant que les décisions architecturales restent vivantes et évoluent avec le projet. Si vous ne les utilisez pas encore, il est peut-être temps de les intégrer dans votre workflow de développement !
Ressources :
- adr.github.io pour plus d’informations et des outils.
- adr-tools pour gérer vos ADR depuis la ligne de commande.
Ce guide vous donne une base pour comprendre et adopter les ADR. N’hésitez pas à l’adapter aux spécificités de vos projets et de vos équipes.