RFC и ADR

Буду больше работать.

Джордж Оруэлл — «Скотный двор»

Варианты решения проходят обсуждение и превращаются в короткую запись принятого выбора. — Communication Engineering · RFC и ADR

RFC и ADR часто смешивают, потому что оба говорят о решениях. Их функции различаются.

RFC — запрос на обсуждение значимого изменения. Он создаёт пространство для вопросов, альтернатив и влияния.
ADR — запись архитектурного решения. Она сохраняет контекст, выбор и последствия для будущих участников.

RFC живёт до и во время выбора. ADR — после него.

Когда нужен RFC

RFC оправдан, если изменение:

затрагивает несколько команд или публичный контракт;
дорого откатить;
содержит серьёзный компромисс;
требует миграции;
меняет безопасность, данные или эксплуатацию;
вызывает устойчивое разногласие.

Для маленькой обратимой правки достаточно issue или короткого сообщения. Цель RFC — снизить риск, а не доказать серьёзность автора.

Структура RFC

Abstract: что меняется и зачем.
Контекст и проблема.
Цели и не-цели.
Предлагаемое решение.
Альтернативы и компромиссы.
Миграция и откат.
Безопасность, данные и эксплуатация.
Открытые вопросы.
Способ и срок принятия решения.

Хороший RFC объясняет не только «как», но и пространство выбора.

Структура ADR

ADR короче:

статус;
контекст;
решение;
последствия;
рассмотренные альтернативы;
ссылки на RFC, код и метрики.

ADR не переписывают после изменения истории. Если решение заменено, старую запись помечают superseded и связывают с новой.

Процесс обсуждения

Документ сам не создаёт качественного решения.

Автор публикует черновик достаточно рано.
Указывает, какие части уже фиксированы, а где нужен вклад.
Ревьюеры отделяют блокирующие риски от предпочтений.
Автор отвечает на вопросы в документе, а не только в личных чатах.
Владелец решения фиксирует выбор и несогласия.
После реализации фактические отклонения попадают в ADR или follow-up.

Антипаттерн

Автор приносит 30-страничный RFC после готовой реализации. Любое возражение воспринимается как задержка.

Рабочий вариант

Черновик из двух страниц появляется после исследования проблемы, но до выбора технологии. В нём уже есть ограничения, два варианта и вопросы, на которые нужен опыт соседней команды.

Результат

Влияние становится реальным, а не церемониальным.

Критерий размера

Документ должен быть настолько подробным, насколько нужно для дорогих необратимых частей. Не описывайте очевидную реализацию на десять страниц, но не прячьте миграцию данных в одной строке.

Используйте прогрессивное раскрытие: краткий вывод, диаграмма, главные компромиссы, затем детали и приложения.

Антипаттерны

RFC как разрешение начальства;
документ без владельца решения;
список плюсов без минусов выбранного варианта;
ложная альтернатива, добавленная для вида;
обсуждение только стиля текста вместо риска;
ADR без последствий;
обновление старой записи так, будто прежнего решения не было.

Малый RFC

Для текущего значимого изменения напиши одну страницу: проблема, ограничения, два варианта, рекомендация, главный риск и открытый вопрос. Покажи её человеку, который будет сопровождать решение.