Présenté par Emmanuel Sciara à l'occasion des conférences Agile en Seine le 29 septembre 2020 http://agileenseine.com Vidéo de la conférence disponible sur Youtube : https://youtu.be/-xBuJq4B8qY Les ADRs (Architecture Decision Records) sont un moyen simple, utile et efficace de permettre aux équipes de décider, de documenter, d'organiser et de partager les choix qu'ils font sur leurs architecture et sur leur organisation. Toutefois, leur mise en oeuvre peut empêcher la pleine récolte des bénéfices qu'ils peuvent apporter sans aucun doute apporter. Ce talk explique ce qu'est un ADR, quels en sont les bénéfices, quels sont les pièges de sa mise en oeuvre et comment les éviter. Permettre l'autonomie et l'auto-gestion des équipes sur les décisions structurantes techniques ou organisationnelles.

1. Comment implémenter
efficacement les ADRs
Emmanuel Sciara
Mardi 29 septembre 2020 19:00
1

2. Emmanuel Sciara
Coach Agile, DevOps et Tech
Spécialiste CI/CD et efficacité des centres de
développement
Certifié GCP Professional Data Engineer
emmanuel.sciara@tech-and-brains.com
@esciara
https://www.opinionated-digital-center.org/

3. SPONSORS
3

4. NOS PARTENAIRES
4

5. Comment implémenter
efficacement des ADRs ?
Emmanuel Sciara
5

6. Contexte et Définition
Ecosystème d’une mise en place
Proposition de cycle de vie et outillage
6

7. Contexte et Définition
Ecosystème d’une mise en place
Proposition de cycle de vie et outillage
7

8. Qu’est ce qu’une Décision Architecturale ?
● Choix de technologie
○ Choisir Python pour un service donné
○ Choisir ReactJS plutôt que AngularJS pour le front
● Choix de type d’architecture, de pattern
○ Décider d’utiliser des microservices
● Définition de conventions
○ Choisir un format pour exposer les dates (YYYY-MM-DD HH:mm)
● Au niveau très global (entreprise)...
○ Choisir NodeJS pour tous les services
● ...ou très local (projet)
○ Choisir Micronaut pour les nouveaux services Java
8

9. Finalement, une Décision Architecturale, c’est :
Toute décision structurante
pour le logiciel qu’elle concerne
9

10. Le problème avec les décisions (en général) c’est :
?
?
10

11. Réflexe initial : Documenter… mais en général :
11

12. Code
source
Code
source
Une solution alternatives efficace : les ADRs
Journal de
décisions
12

13. Cycle de vie d’un ADR
source : https://blog.engineering.publicissapient.fr/2019/03/05/architecture-et-documentation-les-adrs/ 13

14. en termes plus formels, un ADR, c’est
Un document...
...qui capture une décision architecturale
que vous avez prise...
...et qui inclut son contexte
et ses conséquences
https://blog.engineering.publicissapient.fr/2019/03/05/architecture-et-documentation-les-adrs/ 14

15. A quoi ça ressemble un ADR
● Exemple en ligne
○ Template d’ADR
○ ADR complexe
○ ADR simple
15

16. A quoi ça ressemble un ADR
● Exemple en ligne
○ Template d’ADR
○ ADR simple
○ ADR plus fourni en information
16

17. A quoi ça ressemble un repository d’ADRs
● Exemple en ligne
○ Pour l’entreprise
○ Pour un projet
17

18. en termes plus formels : Principes de base
● Léger
○ Se concentre sur les informations essentielles d’une décision.
● Partagé
○ Accessibles facilement aux personnes qui en ont besoin.
○ Inclut décideurs, mais surtout personnes en charge de la
concrétisation des décisions.
● Immuable
○ Le journal de décision doit faire apparaître clairement toute
modification dans les décisions qui le constituent.
● Justifié
○ Contient les informations pertinentes pour comprendre une décision et
la remettre en cause si nécessaire.
https://blog.engineering.publicissapient.fr/2019/03/05/architecture-et-documentation-les-adrs/ 18

19. Contexte et Définition
Ecosystème d’une mise en place
Proposition de cycle de vie et outillage
19

20. Introduire les ADRs dans votre environnement
Besoin d’une culture participative
“L’adhésion découle de la participation”
et d’une culture de coding architects ou
de knowledge-sharing architects
http://ithare.com/knowledge-sharing-architects-as-an-alternative-to-coding-architects/
20

21. Les challenges de l’ancrage des ADRs
Le sentiment qu’il est important d’enregistrer les décisions architecturales
doit être partagé par l’équipe et porté par une ou deux personnes influentes
21

22. Recettes pour favoriser l’ancrage des ADRs
Ne choisir que des décisions qu’il paraît
important de partager et de commenter
Avoir un ou deux hérauts (influents)
22

23. Recettes pour favoriser l’ancrage des ADRs (suite)
Discuter et arriver
au plus près d’un consensus
avant de commencer à écrire Ecrire l’ADR dès qu’un consensus suffisant
est atteint et proposer une Pull Request
23

24. Recettes pour favoriser l’ancrage des ADRs (suite)
Communiquer largement,
formellement et informellement,
la mise à disposition du nouvel ADR
Encourager l’échange
24

25. Qualités d’un héraut
Leadership collaboratif
Capacité d’animation et de fédération
Tranche en cas de non-décision
25

26. les anti-patterns : le héraut-clerc
Récolte les avis sans vraiment en avoir
Pas de connaissance ou d’expérience ou de
capacité d’analyse suffisante pour
guider/accompagner les échanges
N’est pas suffisamment fédérateur
Les débats peuvent tourner à la foire
d’empoigne, ou perdre leur valeur et
légitimité => l’engagement s’effrite
26

27. les anti-patterns : le héraut (ou participant)-tyran
A des opinions très tranchées sur beaucoup
de domaines
Impose ses croyances sous le couvert de
débats pseudo-ouverts
=> Désengagement des équipes
27

28. les anti-patterns : mauvais choix d’outils
L’enfer des emails et des versions
Pas de système de revues global et efficace
Pas de navigation web ou intuitive et
emplacements séparés
Pas de change log/decision log automatique
et/ou efficace
Workflow difficilement automatisable
+
/
28

29. les anti-patterns : (potentiel) mauvais choix d’outils
Pas de vue centralisée du change
log/decision log (seulement individuel)
Emplacement différent
Pas de support natif pour les
workflows custom
/ WIKIS
29

30. Rester sur les outils de prédilection
Collaboratif par essence
Déjà utilisé extensivement par les
équipes techniques
Fonctionnalité de revue collégiale
puissantes et complètes
Traçage puissant avec historique
détaillé
Automatisation et workflows
/
30

31. Git + GitLab/GitHub + CI + Markdown
● Collaboratif par essence
● Déjà utilisé extensivement par les équipes techniques
○ Encourage la participation de ceux qui font
● Fonctionnalité de revue collégiale puissantes et
complètes
● Traçage puissant avec historique détaillé
● Capacité d’automatisation des workflows, avec tests de
validité, vérifications et/ou assurance de conformité
● Format Markdown simple et efficace
31

32. Outils qui ne marche pas
● Office 365 Word + Sharepoint/Teams
○ L’enfer des email et des versions
○ Pas de système de revues global et efficace
○ Pas de navigation web ou intuitive et emplacements séparés
○ Pas de change log/decision log automatique et/ou efficace
○ Workflow difficilement automatisable
● Confluence/wiki
○ Pas de vue centralisée du change log/decision log (seulement
individuel)
○ Pas de support natif pour les workflows custom
○ Emplacement différent
32

33. Contexte et Définition
Ecosystème d’une mise en place
Proposition de cycle de vie et outillage
33

34. Problèmes rencontrés
● Simple cycle de vie, mais pas de processus
● Outils existants limités => beaucoup de tâches manuelles
et sujettes à erreurs
Conséquences :
● Incohérences dans les statuts
● Historiques raturés et peu clairs
● Règles de nommages mal respectées
● ...
34

35. Processus ou pas processus ?
● Permet une standardisation
sur toutes les équipes
● Rend possible une
automatisation
● Permet d’avoir des historiques
propres et cohérents
● Trop peu d’ADR
● Pris en charge par une poignée
de personnes
● Lourdeurs supplémentaires non
nécessaires
35

36. Outils ou pas outils ?
● Automatise les tâches
manuelles récurrentes
● Permet validation des normes
et vérification de cohérence
● Assure des historiques
propres et cohérents
● Outils supplémentaire
comprendre et à maîtriser
● Pris en charge par une poignée
de personnes (pas besoin
d’automatisation)
36

37. Pour les bigs : Créer un processus clair et cohérent
Besoin de processus claires, permettant et fédérant les
interactions pour des échanges plus faciles et plus riches
● De la nouvelle proposition à l’acceptation ou le rejet
● De la proposition de dépréciation à la dépréciation
● De la proposition de remplacement au remplacement
37

38. Pour les bigs : Créer un processus claire et cohérent
Besoin de processus claires, permettant et fédérant les
interactions pour des échanges plus faciles et plus riches
● De la nouvelle proposition à l’acceptation ou le rejet
● De la proposition de dépréciation à la dépréciation
● De la proposition de remplacement au remplacement
38

39. 39

40. 40

41. 41

42. 42

43. 43

44. Processus dans un repository d’ADR
● Exemple en ligne
○ Pour l’entreprise
44

45. Ressources
● Opinionated Digital Center
○ Site web (version fr, version en)
○ Repo git avec :
■ Outil de gestion des ADRs (PyADR/git adr)
■ Exemple de repo entreprise avec pipeline de CI/CD faisant :
● Génération automatique de l’index des ADRs
● Validation automatique des ADRs
○ format du contenu
○ nom de fichier
○ numéro d’identifiant
● Génération automatique de changelog
● Bump automatique de la version du repo (suit le semantic
versioning)
● Release automatique de la nouvelle version du repo
45

46. Outils et automatisation à la rescousse
● Supprimer le travail rébarbatif
● Minimiser les erreurs possibles
● Générer un historique claire et sans ratures
● Assurer l’utilisation de conventions de nommages
mnémotechniques
● Assurer la validité et la mise à jour des méta-données
● Assurer l’application d’un processus qui fait sens pour
tout le monde
● Vérifier l’intégrité du repository
46

47. Démonstration
De la proposition à l’acceptation ou le rejet d’un ADR
Mise en garde: on suppose ici que ce sont les développeurs
et les architectes codeurs qui sont la sources créatives des
ADRs. Nous utilisons donc leurs outils de prédilection, qui
sont techniques.
47

48. Quelques remarques
● Utilisation de l’usine d’intégration continue (GitLab CI,
GitHub Workflows, Jenkins, ...)
● Création de l’outil de ligne de commande “git adr”
● Navigation et visualisation directes des ADRs sur
navigateur web
● Création automatique de l’index des ADRs
● Calcul et assignation automatique de l’identifiant de
l’ADR
● Utilisation intensive de branches et de Pull Requests
● Création et nommage automatique des branches pour
indiquer clairement l’objet des revues
● Création automatique de messages de commit pour un 48

49. MERCI !emmanuel.sciara@tech-and-brains.com
@esciara
https://www.opinionated-digital-center.org/
Présentation disponible sur
https://www.linkedin.com/in/emmanuelsciara/
49

50. Comment implémenter efficacement les ADRs
— Emmanuel Sciara —
Mardi 29 septembre 2020 19:00
https://roti.express/r/aes20-01
2
A vos feedback
!
50