Добавил документацию и описание репозитория

2026-06-13 17:10:53 +03:00
parent 82a81c16af
commit 5b53f4e8e8
12 changed files with 647 additions and 0 deletions
@@ -0,0 +1,59 @@
+# 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 | [Go и доставка одним бинарём](ADR-2026-06-13-go-single-binary.md) | —      |