63 lines
4.1 KiB
Markdown
63 lines
4.1 KiB
Markdown
# Architecture Decision Records (ADR)
|
||
|
||
Журнал значимых архитектурных решений по jellybit. Одна запись — одно
|
||
решение. ADR пишем **постфактум**, когда решение принято и зафиксировано
|
||
в коде/проекте: идеи и неподтверждённые планы живут в `docs/drafts`, а не
|
||
в ADR. Записи **неизменяемы**: передумали → не правим старую, заводим
|
||
новую и помечаем старую.
|
||
|
||
Главная ценность записи — сохранить **почему**: намерение и причинность.
|
||
Это важнее аккуратности оформления и полноты остальных секций.
|
||
|
||
Формат и процесс унаследованы от соседнего проекта umbar.
|
||
|
||
## Когда заводить ADR
|
||
|
||
- Выбор технологии или инструмента.
|
||
- Структурные решения (хранилище, организация компонентов, протоколы).
|
||
- Решения с долгосрочными последствиями или дорогим откатом.
|
||
- **Намеренный отказ** от очевидного подхода — чтобы потом не
|
||
переоткрывать «а почему мы не сделали X».
|
||
|
||
Не заводить для рутины (бамп версии зависимости, добавление эндпоинта по
|
||
накатанной схеме) и того, что и так видно из кода и git.
|
||
|
||
## Соглашения
|
||
|
||
- **Имя файла = идентификатор:** `ADR-ГГГГ-ММ-ДД-kebab-slug.md`.
|
||
Идентификатор — имя без `.md`. Slug — латиницей.
|
||
- **Дата** — когда решение реально принято.
|
||
- Несколько ADR за один день различаются по slug.
|
||
- **Заголовок в файле:** `# Человеческий заголовок` (без даты и ID — они
|
||
в имени файла и в строке «Дата»).
|
||
- Секция **«Рассмотренные варианты» — опциональна**: оставляй её, только
|
||
если альтернативы реально рассматривались.
|
||
- Шаблон новой записи — [`template.md`](template.md).
|
||
|
||
## Статусы
|
||
|
||
Активная запись статуса **не имеет**. Статус появляется, только когда
|
||
запись теряет силу, и значений всего два:
|
||
|
||
- `заменено на ADR-ГГГГ-ММ-ДД-slug` — решение пересмотрено новой ADR.
|
||
- `устарело` — решение потеряло смысл и замены нет.
|
||
|
||
## Замена и устаревание
|
||
|
||
1. Заводим новую ADR; в её «Контексте» — строка
|
||
«Заменяет ADR-ГГГГ-ММ-ДД-slug».
|
||
2. В старой ADR добавляем строку `- Статус: заменено на ADR-…` сразу под
|
||
датой. Тело не трогаем — это часть истории.
|
||
3. Обновляем статус старой записи в индексе ниже.
|
||
|
||
## Список записей
|
||
|
||
Новые сверху.
|
||
|
||
| Дата | Запись | Статус |
|
||
| ---------- | ---------------------------------------------------------------- | ------ |
|
||
| 2026-06-13 | [Авто-раскладка только при матче в метабазе](ADR-2026-06-13-auto-link-requires-db-match.md) | — |
|
||
| 2026-06-13 | [Docker как единица деплоя](ADR-2026-06-13-docker-deploy.md) | — |
|
||
| 2026-06-13 | [Хардлинки вместо копирования и симлинков](ADR-2026-06-13-hardlinks.md) | — |
|
||
| 2026-06-13 | [Go и доставка одним бинарём](ADR-2026-06-13-go-single-binary.md) | — |
|