# 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)          | —      |
| 2026-04-04 | [Apprise как шлюз уведомлений](ADR-2026-04-04-apprise-notifications.md)                        | —      |
| 2025-12-13 | [Обновление ОС пересборкой на свежем сервере](ADR-2025-12-13-os-upgrade-via-server-rebuild.md) | —      |
| 2025-12-07 | [Данные приложений на отдельном диске](ADR-2025-12-07-app-data-on-separate-disk.md)            | —      |
| 2025-05-07 | [Authelia вместо Keycloak для SSO](ADR-2025-05-07-authelia-sso.md)                             | —      |
| 0000-00-00 | [Вести историю решений в виде ADR](ADR-0000-00-00-record-architecture-decisions.md)            | —      |