Замещение решений

Замещение решений — это процесс, при котором старый ADR (Architecture Decision Record) заменяется новым, когда старое решение больше не применимо. Вместо удаления старого ADR, его статус помечают как 'Superseded by ADR-NNN', а затем создают новый ADR, который объясняет изменения и исходный контекст. Такой подход позволяет сохранить полезную историю принятия решений, что крайне важно для будущих разработчиков и архитекторов, которые могут столкнуться с теми же вопросами и решениями.

Как это работает

При замене старого ADR новым, следует выполнить несколько шагов. Во-первых, необходимо создать новый ADR (ADR-NNN) и указать в секции Context ссылку на старый ADR. Затем следует объяснить, почему старое решение больше не применимо. Это может быть связано с новыми требованиями, ограничениями или технологиями. Важно также обновить статус старого ADR, пометив его как 'Superseded by ADR-NNN' и добавив одну строку, которая кратко описывает замену. Оба ADR остаются в репозитории навсегда, чтобы сохранить полную историю принятия решений.

Когда применять

Замещение решений применяется при значительных изменениях в проекте, таких как переход на новую БД, изменение контракта API или изменение модели развертывания. Не следует заменять ADR за незначительные корректировки, которые укладываются в рамки исходного решения. Замена должна быть обоснована значительными изменениями в underlying-фрейминге проекта.

Типичные ошибки

Удаление старых ADR

Удаление старых ADR разрушает исторический record, что делает невозможным для будущих разработчиков понимание, почему текущее решение отличается от более ранних выборов. Сохранение старых решений позволяет видеть полную картину эволюции проекта.

Забыли пометить старый ADR

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

Замещение без обоснования

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