68 lines
4.7 KiB
Markdown
68 lines
4.7 KiB
Markdown
# Architecture Decision Records (ADR)
|
|
|
|
Журнал значимых архитектурных и инфраструктурных решений по серверу.
|
|
Одна запись — одно решение. ADR пишем **постфактум**, когда изменение
|
|
уже сделано: идеи, планы и обсуждения живут в [`../drafts/`](../drafts),
|
|
а в ADR попадает только то, что реализовано. Записи **неизменяемы**:
|
|
передумали → не правим старую, а заводим новую и помечаем старую.
|
|
|
|
Чем ADR отличается от журналов в `../drafts/`: drafts — оперативная
|
|
хроника и черновики («что делаю / собираюсь сделать»), ADR — фиксация
|
|
выбора и его обоснования («почему сделал так, а не иначе»).
|
|
|
|
Главная ценность записи — сохранить **почему**: намерение и причинность.
|
|
Это важнее аккуратности оформления и полноты остальных секций.
|
|
|
|
## Когда заводить ADR
|
|
|
|
- Выбор технологии или инструмента (Caddy vs Nginx, restic vs borg).
|
|
- Структурные решения (схема бэкапов, организация плейбуков, сеть).
|
|
- Решения с долгосрочными последствиями или дорогим откатом.
|
|
- **Намеренный отказ** от очевидного подхода — чтобы потом не
|
|
переоткрывать «а почему мы не сделали X».
|
|
|
|
Не заводить для рутины (бамп версии образа, добавление сервиса по
|
|
накатанной схеме) и того, что и так видно из кода и git.
|
|
|
|
## Соглашения
|
|
|
|
- **Имя файла = идентификатор:** `ADR-ГГГГ-ММ-ДД-kebab-slug.md`.
|
|
Идентификатор — имя без `.md` (например `ADR-2026-05-24-adr-process`).
|
|
Slug — латиницей.
|
|
- **Дата** — когда изменение реально сделано (можно задним числом, а не
|
|
дата оформления записи).
|
|
- Несколько ADR за один день различаются по slug.
|
|
- **Заголовок в файле:** `# Человеческий заголовок` (без даты и ID — они
|
|
в имени файла и в строке «Дата»).
|
|
- Секция **«Рассмотренные варианты» — опциональна**: оставляй её, только
|
|
если альтернативы реально рассматривались.
|
|
- Шаблон новой записи — [`template.md`](template.md).
|
|
- Исключение: основополагающая мета-запись о самом процессе ADR
|
|
использует дату-сентинел `0000-00-00`, чтобы всегда оставаться в самом
|
|
низу списка. Реальные записи такую дату не используют.
|
|
|
|
## Статусы
|
|
|
|
Активная запись статуса **не имеет**. Статус появляется, только когда
|
|
запись теряет силу, и значений всего два:
|
|
|
|
- `заменено на ADR-ГГГГ-ММ-ДД-slug` — решение пересмотрено новой ADR.
|
|
- `устарело` — решение потеряло смысл и замены нет.
|
|
|
|
## Замена и устаревание
|
|
|
|
1. Заводим новую ADR; в её «Контексте» — строка
|
|
«Заменяет ADR-ГГГГ-ММ-ДД-slug».
|
|
2. В старой ADR добавляем строку `- Статус: заменено на ADR-…` сразу под
|
|
датой. Тело не трогаем — это часть истории.
|
|
3. Обновляем статус старой записи в индексе ниже.
|
|
|
|
## Список записей
|
|
|
|
Новые сверху.
|
|
|
|
| Дата | Запись | Статус |
|
|
| ---------- | ------------------------------------------------------------------------------------- | ------ |
|
|
| 2026-05-23 | [Переезд сервера с Yandex Cloud на Timeweb VPS](ADR-2026-05-23-migrate-to-timeweb.md) | — |
|
|
| 0000-00-00 | [Вести историю решений в виде ADR](ADR-0000-00-00-record-architecture-decisions.md) | — |
|