From 2640ef4fd69fb159f4728d4c6bfe5cd431e10ad2 Mon Sep 17 00:00:00 2001 From: Mikhail Yenuchenko Date: Tue, 4 Aug 2026 23:16:46 +0300 Subject: [PATCH] docs: plan for architecture.md and development.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Records the decision to add these two docs (out of ТЗ scope but needed so project structure and the dev loop don't live only in memory/context), with a new D8 task and non-blocking release-gate note. Co-Authored-By: Claude Sonnet 5 --- docs/documentation-plan.md | 53 ++++++++++++++++++++++++++++++++------ 1 file changed, 45 insertions(+), 8 deletions(-) diff --git a/docs/documentation-plan.md b/docs/documentation-plan.md index 257714e..3a2bab3 100644 --- a/docs/documentation-plan.md +++ b/docs/documentation-plan.md @@ -33,14 +33,37 @@ ### Рабочие документы проекта (не поставка, но обязаны быть верны) [specification.md](specification.md) — ТЗ v1.0, источник истины по требованиям. -[implementation-plan.md](implementation-plan.md) — открытые вопросы и линия 2.x. +[implementation-plan.md](implementation-plan.md) — открытые вопросы для v1.0/v1.x. +[roadmap.md](roadmap.md) — линия 2.x.x. [progress.md](progress.md) — живой трекер, читается первым после `/clear`. [security.md](security.md) — принятые риски. Этот файл — план по документации. -**Границы:** отдельные `CONTRIBUTING.md`, `docs/architecture.md`, man-страницы и -сайт документации ТЗ **не требует** и в объём v1.x не входят. Dev-петля (сборка -и тесты на dev-сервере) остаётся в `progress.md` и в память проекта — выносить -её в поставляемую документацию не нужно. +**Новое: `docs/architecture.md` и `docs/development.md` — нужны, решение +принято.** ТЗ их не требует (ТЗ 11 не относит их к обязательной поставке), но +без них понимание устройства и повторная сборка проекта держатся только на +памяти и контексте текущей сессии — то есть не переживают её потерю ни для +будущего контрибьютора, ни для будущего прохода без доступа к истории чата. +Обе — рабочие документы проекта (не часть поставки пользователю, не +упоминаются в README как обязательные), задача заведена в разделе 4 (**D8**). + +- `docs/architecture.md` — компоненты контейнера (`supervisord`, + `postfix`, `opendkim`, `panel`, milter-цепочка) и как они связаны; путь + письма через тракт (SMTP submission → milter'ы → OpenDKIM → доставка); + что читает/пишет `/data` и в каком формате; где проходит граница + привилегий (root vs непривилегированный uid панели) и почему — + источник истины: код (`build/supervisord.conf`, `internal/`), а не + ТЗ, план сверки — тот же метод из раздела 2. +- `docs/development.md` — как собрать и прогнать тесты локально (Go + локально, без Docker — см. память проекта), когда нужен полный + контейнерный цикл на dev-сервере (сборка образа, milter/почтовые + изменения) и почему локальной сборки недостаточно, порядок ручной + проверки на `selfpost.example.com` перед мёржем. Заменяет часть, что + раньше держалась только в памяти проекта и `progress.md` — там + остаётся текущее состояние и следующий шаг, а не воспроизводимая + процедура. + +**Границы (без изменений):** отдельные `CONTRIBUTING.md`, man-страницы и сайт +документации ТЗ по-прежнему не требует и в объём v1.x не входят. --- @@ -222,6 +245,18 @@ DNS-карточка домена); прогрев IP; смысл фиксиро **D7. Регресс-защита (см. раздел 5).** +**D8. Новые документы: `docs/architecture.md` и `docs/development.md`.** +Пишутся с нуля (в разделе 3 их нет — это не расхождение с кодом, а +отсутствовавший артефакт). `architecture.md` сверяется тем же методом, что и +остальное (раздел 2): по факту компоновки образа и кода, не по памяти. +`development.md` фиксирует уже существующий, но нигде не описанный процесс +(Go локально / полный цикл на dev-сервере для Docker-зависимых изменений). +*Готово, когда:* `architecture.md` перечисляет все managed-процессы из +[build/supervisord.conf](../build/supervisord.conf) и путь письма через +milter-цепочку без противоречий коду; `development.md` позволяет с нуля +повторить локальную сборку + прогон тестов и понять, когда нужен +dev-сервер, не заглядывая в память проекта. + --- ## 5. Чтобы не разошлось снова @@ -243,6 +278,8 @@ DNS-карточка домена); прогрев IP; смысл фиксиро ## 6. Гейт релиза Документационный проход — часть того же гейта, что e2e (C.4) и ревизия -безопасности (D.5): **D1–D6 закрыты до тега**. D7 — желателен, но тег не -блокирует. Находки, обнаруженные позже, дописываются сюда, а не исправляются -молча: этот файл — журнал состояния документации, а не одноразовый список дел. +безопасности (D.5): **D1–D6 закрыты до тега**. D7 и D8 — желательны, но тег не +блокируют: D8 не покрывает пробел против ТЗ (архитектура/разработка не входят +в обязательную поставку), поэтому может тянуться в фон после релиза. Находки, +обнаруженные позже, дописываются сюда, а не исправляются молча: этот файл — +журнал состояния документации, а не одноразовый список дел.