Comment et pourquoi écrire une décision d’architecture ?

En 2019, un incendie ravageait les parties supérieures de Notre-Dame de Paris. Si nous retraçons ses 850 ans d’histoire, nous verrons les différentes étapes qui l’ont façonnée. Ainsi Notre-Dame de Paris telle que nous la connaissons n’est pas la même que celle que les Parisiens ont connu à la fin du 13e siècle.

Comment relater l’évolution de son architecture ? Tout simplement en consultant les registres tenus par les corps de métiers qui ont travaillé à la construire, à la rénover et à la modifier. 

Quel est le rapport avec le développement de projets informatiques ?

Contrairement à l’histoire de Notre-Dame de Paris, dont l’évolution court sur plusieurs siècles, nos projets informatiques évoluent au fur et à mesure des sprints (et rarement sur plus d’une décennie ;) ).

Nous faisons des choix qui impactent l’architecture système ou le logiciel pratiquement dans chaque version.

Voici différentes raisons qui modifieront notre architecture initiale :

• Répondre à un nouveau besoin fonctionnel (envoyer une notification à une utilisatrice ou à un utilisateur quand l’expédition de colis est effectuée), ou à une nouvelle exigence technique (l’application doit publier des métriques pour mieux être observée),
• Choisir parmi des options technologiques (SQL ou NoSQL pour la persistance des données), des outils (Terraform vs CloudFormation), des librairies ou des frameworks.
• Refondre le code existant…

C’est ce qu’on appelle une décision d’architecture.

L’équipe l’enregistre dans un inventaire de décisions d’architecture (ADL ou Architecture Decision Log) ce qui constitue alors un journal de bord du projet.

Comment tracer efficacement ces décisions ? Qu’est-ce qu’un enregistrement de décision d'architecture ? Quels bénéfices apportent-ils ? Comment écrire ce document ?

Comment s’organiser pour écrire une décision d’architecture ?

La solution la plus simple pour tracer ces décisions est d’organiser une réunion où toutes les parties intéressées participent. Son ordre du jour est généralement le suivant :

1. Énoncer le contexte de la décision à prendre
2. Décrire la problématique à adresser
3. Lister les contraintes qui influencent la décision finale
4. Lister les différentes options à discuter
5. Décider quelle sera l’option retenue après le débat.

Pour être efficace, un scribe est désigné pour écrire un compte rendu de cette réunion afin de  tracer les échanges. Les intervenants peuvent préparer la réunion en listant les options envisagées. Lors de la réunion, les intervenants peuvent aussi proposer de nouvelles options qui seront discutées.

Les participants discutent ensuite de chacune des propositions en comparant leurs avantages et inconvénients. Des comparaisons de caractéristiques techniques ou de tests de performance peuvent aussi être évoqués lors de ces discussions pour argumenter le choix d’une des options.

À la fin des échanges, une décision peut être prise pour répondre au besoin. Un compte rendu est alors envoyé aux différents intervenants pour valider ou invalider la décision. Ce compte-rendu est aussi appelé ADR (Architecture Decision Record ou enregistrement de décision d’architecture). L’ADR est immuable : une fois la réunion finie, les choix, leurs points positifs et négatifs ne peuvent pas être modifiés.

Le compte-rendu possède un état qui lui seul peut être changé. Voici les états d’un ADR communément acceptés :

• Proposé : L’ADR peut être initié pour préparer la décision d’architecture. Le document peut décrire les différents points nommés dans l’agenda. Le compte-rendu reste dans cet état tant qu’il n’a pas été validé par l’ensemble de l’équipe.
• Accepté : Celui-ci est revu et peut être accepté si un commun accord a été trouvé.
• Rejeté : Le groupe peut aussi la rejeter à l’issue de la réunion quand aucun choix ne répond aux facteurs de décision par exemple.
• Déprécié : Une nouvelle fonctionnalité ou un changement d’architecture rend caduque la solution implémentée. Dans ce cas, celui-ci doit être déprécié.
• Remplacé: Un nouvel ADR doit être créé si un élément ou plusieurs éléments de l’ADR doit être modifié. En effet, un ADR est immuable et seul son statut peut être changé.

Le flux de transitions entre les différents états peut être symbolisé grâce au schéma suivant :

Comment stocker ensuite le compte rendu de décision ?

Nous devons enregistrer ce rapport dans un format qui ne nécessite aucun logiciel en particulier. Un document texte est alors amplement suffisant. Pour faciliter la lecture, je recommande le type de fichier Markdown ou AsciiDoc. De plus en plus d’applications génèrent directement le rendu et nous pouvons imaginer par exemple de pouvoir générer différents formats dans une CI par exemple.

Ces fichiers doivent être entreposés dans un espace commun à l’équipe comme un Google Drive, un dossier partagé Dropbox, une page dans un wiki ou autre. Dans ma mission courante, nous les stockons directement dans le dépôt Git du projet.

Pour simplifier l’accès à l’information, nous recommandons de mettre en place une nomenclature sur les noms des fichiers. Voici, par exemple, notre convention de nommage :

• Le nom commence par un index composé de trois chiffres. Le scribe l’incrémentera à la création du document.
• Le nom contient un résumé de la problématique à résoudre.
• Le nom utilise des minuscules et des soulignements. C’est un équilibre entre la lisibilité et la facilité d’usage du système.
• Son extension est de type Markdown.

Et des exemple de fichiers qui suivent cette convention :

• 001_choose_database.md
• 002_choose_infra_as_code_tooling.md
• 003_format_timestamp.md

Contenu d’un enregistrement de décision d’architecture

Plusieurs modèles d’ADR peuvent être trouvés sur la toile. Je conseille ce dépôt GitHub qui en recense différents : https://github.com/joelparkerhenderson/architecture-decision-record.

Dans notre équipe, nous utilisons ce modèle d’ADR issu du dépôt Git https://github.com/nyudlts/adr-templates. Il a l’avantage d’être simple tout en restant complet.

Même si l’équipe choisit un format d’ADR issu d’un de ces dépôts, elle doit se l’approprier et choisir les éléments nécessaires pour simplifier l’archivage des décisions. Néanmoins, certains champs sont obligatoires comme nous le verrons dans la suite de l’article.

Le résumé de l’ADR

# Use Markdown Architectural Decision Records tool

* Status: accepted <!-- optional -->

* Deciders: Riri, Fifi, Loulou, Uncle Donald <!-- optional -->

* Date:  2022-10-17 <!-- optional -->

Il est nécessaire de comprendre pourquoi cette décision d’architecture existe. Pour cela, il faut donner un résumé :

• Un titre court qui résume le problème. Par exemple : Use Markdown Architectural Decision Records
• Le statut de l’ADR : Quel est le statut actuel de l’ADR ;
• La liste des intervenants présents lors de la réunion ;
• La date de la dernière mise à jour de l’ADR.

Le contexte de l’ADR

## We want to record architectural decisions made in this project. We want to record architectural decisions made in this project. Which tool(s) should we use to manage these records? 

Cette partie décrit le contexte et la problématique à résoudre en deux ou trois phrases. L’idéal est alors de formuler ce paragraphe sous forme de question.

Les critères de choix

Il est nécessaire de définir les contraintes et les critères qui pourront faire ressortir une option parmi toutes celles qui sont envisagées.

Les contraintes peuvent être techniques, sur les perspectives d’évolution du produit, sur des critères financiers ou temporels…

## Decision Drivers <!-- optional -->

* Easy to operate

* Static document generator and compatible with Gitlab pages

* ADR document format must be markdown

Les différentes options envisagées

Le but de cette partie est de lister les différentes solutions au problème posé. Il faut lister objectivement et sans à priori toutes les solutions (même les plus simples).

## Considered Options

* Log4brains: architecture knowledge base (command-line + static site generator)

* ADR Tools: command-line to create ADRs

* adr-viewer: static site generator

* Home made solution: Use Gitlab CI to generate html files from markdown

La solution retenue

Il faut identifier la solution retenue pour résoudre le problème, avec la justification de ce choix.

### Positive Consequences <!-- optional -->

* [e.g., improvement of quality attribute satisfaction, follow-up decisions required, …]

* …

### Negative Consequences <!-- optional -->

* [e.g., compromising quality attribute, follow-up decisions required, …]

* …

Les conséquences positives et négatives apportées par la solution retenue

Cette partie doit lister les conséquences de la décision (aussi bien positives que négatives). Cette partie est optionnelle et pour ma part, je ne l’ai jamais vu dans les ADR produits par l’équipe.

## Decision Outcome

Chosen option: "Log4brains", because it includes the features of all the other tools, and even more.

Les avantages et inconvénient des options

Pour chacune des options envisagées, donner les avantages et inconvénients apportés par la solution. Cela facilitera les échanges et les discussions : des tests techniques, des retours d’expériences peuvent être apportés pour alimenter cette partie.

## Pros and Cons of the Options <!-- optional -->

### Option 1 : Log4brains

* Good, because Apache v2 License is authorized by our organization

* Good, because it is integrated with popular IDE to easily write ADR

* Good, because it can generate a static web site and it is compatible with Gitlab Pages

* Good, because architecture decision record template is customizable

* Good, because it is well integrated with CICD pipelines

* Bad, because it is developed in Javascript and Javascript environment is necessary

* … <!-- numbers of pros and cons can vary -->

#### ...

#### Option 4 : Home made solution: Use Gitlab CI to generate html files from markdown

* Good, because we can manage our format and template

* Good, because license is authorized by our organization

* Bad, because we need to develop our proper tool

* Bad, because we need to maintain this tool

* Bad, because we do not have development knowledge in our team

Les liens éventuels entre les ADR

Cette dernière partie, optionnelle, liste les liens entre les différents ADR. Par exemple, si un ADR remplace un autre ADR ou si le contexte d’un ADR fait suite à une décision déjà prise précédemment.

### Links <!-- optional -->

* [Link type] [Link to ADR] <!-- example: Refined by [ADR-0005](0005-example.md) -->

* … <!-- numbers of links can vary -->

# [short title of solved problem and solution]

* Status: [proposed | rejected | accepted | deprecated | … | superseded by [ADR-0005](0005-example.md)] <!-- optional -->

* Deciders: [list everyone involved in the decision] <!-- optional -->

* Date: [YYYY-MM-DD when the decision was last updated] <!-- optional -->

Technical Story: [description | ticket/issue URL] <!-- optional -->

## Context and Problem Statement

[Describe the context and problem statement, e.g., in free form using two to three sentences. You may want to articulate the problem in form of a question.]

## Decision Drivers <!-- optional -->

* [driver 1, e.g., a force, facing concern, …]

* [driver 2, e.g., a force, facing concern, …]

* … <!-- numbers of drivers can vary -->

## Considered Options

* [option 1]

* [option 2]

* [option 3]

* … <!-- numbers of options can vary -->

## Decision Outcome

Chosen option: "[option 1]", because [justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force force | … | comes out best (see

below)].

### Positive Consequences <!-- optional -->

* [e.g., improvement of quality attribute satisfaction, follow-up decisions required, …]

* …

### Negative Consequences <!-- optional -->

* [e.g., compromising quality attribute, follow-up decisions required, …]

* …

## Pros and Cons of the Options <!-- optional -->

### [option 1]

[example | description | pointer to more information | …] <!-- optional -->

* Good, because [argument a]

* Good, because [argument b]

* Bad, because [argument c]

* … <!-- numbers of pros and cons can vary -->

#### [option 2]

[example | description | pointer to more information | …] <!-- optional -->

* Good, because [argument a]

* Good, because [argument b]

* Bad, because [argument c]

* … <!-- numbers of pros and cons can vary -->

#### [option 3]

[example | description | pointer to more information | …] <!-- optional -->

* Good, because [argument a]

* Good, because [argument b]

* Bad, because [argument c]

* … <!-- numbers of pros and cons can vary -->

### Links <!-- optional -->

* [Link type] [Link to ADR] <!-- example: Refined by [ADR-0005](0005-example.md) -->

* … <!-- numbers of links can vary -->

Bénéfices de la gestion documentaire des décisions

Comme nous l'avons vu, un inventaire de décisions d’architecture constitue un journal de bord de l’équipe pour tracer l’historique des choix faits pendant le développement logiciel et du produit.

Cet inventaire recense les informations essentielles de l’architecture du logiciel qui peut être revue à tout moment. Le contexte menant à la prise de décision est tracé, ce qui permet de comprendre pourquoi cette implémentation a été choisie par rapport à une autre. Un exemple simple pourrait être, avoir un critère sur l’optimisation des coûts par rapport à la résilience d’une architecture.

C’est aussi un moyen de communication de l’équipe. En effet, toute personne extérieure à l’équipe comprend certains choix technologiques en ayant les avantages et inconvénients. Ce qui facilite entre autres la montée en compétence d’une nouvelle personne dans l’équipe ou encore la communication envers les autres équipes.

Si une personne veut proposer une technologie ou une implémentation, il peut parcourir l’ensemble des ADRs pour voir si celle-ci a déjà été envisagée par l’équipe.

En conclusion, l’inventaire de décisions d’architecture permet de rendre vivante la documentation liée au projet. C’est un bon moyen pour tracer les évolutions de l’architecture du projet. C’est un outil efficace à mettre en place dans une équipe pour faciliter les choix d’implémentation ou de technologies. C’est aussi un bon support pour ouvrir à la discussion. Il faut toutefois être vigilant à l’adhésion de l’équipe à ce processus.

Références

• #1 Documenting Architecture Decisions - Michel Nygard - https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions
• #2 Technology Radar - ThoughWorks - https://www.thoughtworks.com/radar/techniques/lightweight-architecture-decision-records
• #3 Scaling the Practice of Architecture - Martin Fowler -https://martinfowler.com/articles/scaling-architecture-conversationally.html
• #4 When Should I write an Architecture Decision Record - Spotify Engineering - https://engineering.atspotify.com/2020/04/when-should-i-write-an-architecture-decision-record/
• #5 Ensemble d’outils sur Github.com pour gérer facilement ses ADRs - https://github.com/topics/architecture-decision-records
• #6 AWS - Processus ADR - https://docs.aws.amazon.com/fr_fr/prescriptive-guidance/latest/architectural-decision-records/adr-process.html
• #7 Des templates pour écrire ses ADR - https://github.com/joelparkerhenderson/architecture-decision-record