Architecture Decision RecordПроцес записів архітектурних рішень AWS
Запис архітектурного рішення (ADR) — це документ, що описує вибір, який робить команда щодо суттєвого аспекту програмної архітектури, яку вона планує побудувати. Кожен ADR описує архітектурне рішення, його контекст і його наслідки. ADR мають стани, а отже проходять життєвий цикл. Приклад ADR дивіться в додатку.
Результатом процесу ADR є набір записів архітектурних рішень. Цей набір утворює журнал рішень. Журнал рішень надає контекст проєкту, а також детальну інформацію про впровадження та проєктування. Учасники проєкту переглядають заголовки кожного ADR, щоб отримати уявлення про контекст проєкту. Вони читають ADR, щоб заглибитися в реалізацію проєкту та вибір проєктних рішень.
Коли команда приймає ADR, він стає незмінним. Якщо нові відомості вимагають іншого рішення, команда пропонує новий ADR. Коли команда приймає новий ADR, він замінює попередній ADR.
Обсяг процесу ADR
Учасникам проєкту слід створювати ADR для кожного архітектурно значущого рішення, що впливає на програмний проєкт або продукт, зокрема таких (Richards and Ford 2020):
Структура (наприклад, патерни на кшталт мікросервісів)
Нефункціональні вимоги (безпека, висока доступність і відмовостійкість)
Залежності (зв’язаність компонентів)
Інтерфейси (API та опубліковані контракти)
Техніки побудови (бібліотеки, фреймворки, інструменти та процеси)
Функціональні й нефункціональні вимоги — найпоширеніші вхідні дані процесу ADR.
Вміст ADR
Коли команда визначає потребу в ADR, один з учасників команди починає писати ADR на основі шаблону, спільного для всього проєкту. (Приклади шаблонів дивіться в організації ADR на GitHub.) Шаблон спрощує створення ADR і гарантує, що ADR фіксує всю релевантну інформацію. Щонайменше кожен ADR має визначати контекст рішення, саме рішення та наслідки рішення для проєкту та його результатів. (Приклади цих розділів дивіться в додатку.) Одна з найпотужніших рис структури ADR полягає в тому, що вона зосереджується на причині рішення, а не на тому, як команда його реалізувала. Розуміння того, чому команда ухвалила рішення, полегшує іншим учасникам команди його прийняття та не дозволяє іншим архітекторам, які не брали участі в ухваленні рішення, скасувати його в майбутньому.
Процес запровадження ADR
Кожен учасник команди може створити ADR, але команді слід визначити поняття володіння ADR. Кожен автор, який є власником ADR, має активно підтримувати та доносити вміст ADR. Щоб прояснити це володіння, у наступних розділах цього посібника авторів ADR названо власниками ADR. Інші учасники команди завжди можуть робити внесок в ADR. Якщо вміст ADR змінюється до того, як команда його прийме, власник має схвалити ці зміни.
Після того як команда визначила архітектурне рішення та його власника, власник ADR на початку процесу подає ADR у стані Proposed (запропоновано). ADR у стані «запропоновано» готові до рецензування.
Далі власник ADR ініціює процес рецензування ADR. Мета процесу рецензування ADR — вирішити, чи команда приймає ADR, визнає, що його потрібно доопрацювати, чи відхиляє його. ADR рецензує команда проєкту, включно з власником. Нарада з рецензування має починатися з окремого проміжку часу для читання ADR. У середньому достатньо 10–15 хвилин. Протягом цього часу кожен учасник команди читає документ і додає коментарі та запитання, позначаючи незрозумілі теми. Після фази рецензування власник ADR зачитує кожен коментар і обговорює його з командою.
Якщо команда знаходить дії для покращення ADR, стан ADR залишається Proposed. Власник ADR формулює дії та, у співпраці з командою, призначає виконавця кожної дії. Кожен учасник команди може робити внесок і закривати пункти дій. Відповідальність за повторне планування процесу рецензування лежить на власнику ADR.
Команда також може вирішити відхилити ADR. У цьому разі власник ADR додає причину відхилення, щоб запобігти майбутнім обговоренням тієї самої теми. Власник змінює стан ADR на Rejected (відхилено).
Якщо команда схвалює ADR, власник додає позначку часу, версію та список зацікавлених сторін. Потім власник змінює стан на Accepted (прийнято).
ADR та журнал рішень, який вони утворюють, відображають рішення, ухвалені командою, і надають історію всіх рішень. За можливості команда використовує ADR як орієнтир під час рев’ю коду й архітектури. Окрім виконання рев’ю коду, завдань проєктування та завдань впровадження, учасникам команди слід звертатися до ADR щодо стратегічних рішень для продукту.
Як добра практика, кожна зміна програмного забезпечення має проходити рецензування колегами та потребувати щонайменше одного схвалення. Під час рев’ю коду рецензент може виявити зміни, що порушують один або кілька ADR. У цьому разі рецензент просить автора зміни коду оновити код і ділиться посиланням на ADR. Коли автор оновлює код, колеги-рецензенти схвалюють його, і він зливається в основну кодову базу.
Процес рецензування ADR
Команді слід ставитися до ADR як до незмінних документів після того, як вона їх прийме або відхилить. Зміна наявного ADR вимагає створення нового ADR, налагодження процесу рецензування нового ADR і його затвердження. Якщо команда схвалює новий ADR, власник має змінити стан старого ADR на Superseded (замінено).