docs: remove code-review.md, carry the open items into roadmap
The review's plan is finished — phase 0 (bar the two release-commit steps),
1, 1.5, 2 and 3 are all closed — and what remained in the document was a second
copy of things that already live in architecture.md, security.md, roadmap.md or
the code comments: the GUI compromise table is in panel.css/panel.js/
middleware.go/handlers_auth.go, the single SQLite connection and the dual
cookie names are explained where they are implemented, the accepted gaps are in
security.md, and the model-routing table names progress.md and development.md
as its own source. A second copy of a fact is a place for it to go stale.
Four items were genuinely open and had no other home, so they moved to
roadmap.md rather than disappearing:
- splitting internal/web into subpackages (2.x) — with the reason to wait: the
flat package still reads at 47 files, and both 2.x features grow it, so the
cut is worth making before that growth, not now;
- a consolidated documentation index in the README (v1.x tail);
- the adaptive polling interval for a tab that is visible but idle — the hidden
case is already handled, and the remainder is explicitly allowed to end as
"decided not to";
- CONTRIBUTING.md, already moved to 2.x in the previous commit.
References retargeted: progress.md (7), roadmap.md (5), implementation-plan.md
(1). The CHANGELOG entries that cite the document are left as written — they
describe what happened at the time. The review text stays in git history at
522425a.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
+52
-15
@@ -25,9 +25,9 @@
|
||||
[deploy/docker-compose.yml](../deploy/docker-compose.yml) поле `image:` бампить
|
||||
до версии релиза **в том же коммите**, что и git-тег `vX.Y.Z` — не раньше.
|
||||
Сейчас там `0.1.0`, то есть отстаёт от целевой версии; несовпадение мешает
|
||||
только до первого выката по тегу. Сам тег — последний шаг Фазы 0
|
||||
[code-review.md](code-review.md): содержательная часть гейта (e2e C.4, ревизия
|
||||
§ D) закрыта, режется по явной команде оператора. После тега `release.yml`
|
||||
только до первого выката по тегу. Сам тег — последний шаг релизного гейта:
|
||||
содержательная часть (e2e C.4, ревизия § D) закрыта, режется по явной команде
|
||||
оператора ([progress.md](progress.md)). После тега `release.yml`
|
||||
собирает и публикует `ghcr.io/mixeme/selfpost:X.Y.Z`, поэтому compose с новым
|
||||
тегом и сам тег обязаны появиться вместе — иначе compose неделю ссылается на
|
||||
несуществующий образ.
|
||||
@@ -48,9 +48,9 @@ CHANGELOG `[Unreleased]/Security`, а разделы B.1–B.3 и C.4 вырез
|
||||
[development.md](development.md).
|
||||
3. Перецелить ссылки из документации: [README.md](../README.md) («Open v1.x
|
||||
questions» — открытых вопросов там нет) → [progress.md](progress.md);
|
||||
[code-review.md](code-review.md), [security.md](security.md),
|
||||
[documentation-plan.md](documentation-plan.md), [progress.md](progress.md) и
|
||||
шапку этого файла → на `progress.md`/`security.md`.
|
||||
[security.md](security.md), [documentation-plan.md](documentation-plan.md),
|
||||
[progress.md](progress.md) и шапку этого файла → на
|
||||
`progress.md`/`security.md`.
|
||||
4. В [progress.md](progress.md) убрать шаг «Открыть `implementation-plan.md`» —
|
||||
он выполнен.
|
||||
|
||||
@@ -64,8 +64,23 @@ git-тег `vX.Y.Z`; `implementation-plan.md` в `docs/archive/`, ссылок
|
||||
`raw.githubusercontent.com` — это и есть единственная площадка проекта, зеркал
|
||||
больше нет.)
|
||||
|
||||
**Сводный индекс документации в README.** Ссылки на `docs/` разбросаны по
|
||||
тексту README (блок в шапке плюс упоминания по месту), единого списка нет —
|
||||
читателю, который ищет «а где вообще что», приходится вычитывать документ.
|
||||
Стоит одного абзаца со списком всех файлов `docs/` и одной строкой на каждый.
|
||||
Мелочь, но именно она делает набор документов набором, а не россыпью.
|
||||
|
||||
**Опрос мониторинга у открытой, но незанятой вкладки.** Скрытая вкладка уже не
|
||||
опрашивает сервер (фильтр на `htmx:beforeRequest` в
|
||||
[panel.js](../internal/web/static/panel.js)). Остаток: вкладка на переднем
|
||||
плане, с которой не работают, всё равно ходит раз в 5 с. Кандидат — адаптивный
|
||||
интервал (5 с при активности, 30 с при простое) по `htmx:afterRequest` без
|
||||
изменения `hx-trigger`. Ценность низкая: нагрузка — один SQL-запрос и рендер
|
||||
фрагмента, так что это скорее гигиена, чем экономия. Допустимый исход —
|
||||
осознанно не делать.
|
||||
|
||||
**Send-log vs `mail.log` (частично закрыто).** Persist позиции чтения сделан
|
||||
(Фаза 3 [code-review.md](code-review.md), таблица `logtail_state`): после
|
||||
(таблица `logtail_state`, миграция `0003`): после
|
||||
рестарта панели log-tailer дочитывает пропущенный хвост. Остаётся пересоздание
|
||||
контейнера — `mail.log` не в `/data` и теряется вместе с ним, такие строки
|
||||
навсегда останутся `queued`. Кандидаты, если станет больно: volume для лога,
|
||||
@@ -139,15 +154,37 @@ Windows → сборка и прогон на Debian-сервере, потом
|
||||
[development.md](development.md) и [progress.md](progress.md) — то есть на
|
||||
русском и вперемешку с внутренним состоянием проекта.
|
||||
|
||||
**Почему 2.x, а не v1.x** (перенесено из [code-review.md](code-review.md) § 10,
|
||||
пункт R7, где стояло как «опционально v1.x»). Файл имеет смысл, когда есть
|
||||
кому его читать: у проекта один разработчик и внешнего потока PR нет, поэтому
|
||||
сейчас `CONTRIBUTING.md` был бы документом без аудитории и ещё одним местом,
|
||||
где расходится правда о dev loop. Уместен вместе с тем, что реально открывает
|
||||
проект вовне: английская документация процесса (сейчас RU/EN split — барьер
|
||||
для EN-only контрибьюторов, [code-review.md](code-review.md) § 4) и первый
|
||||
внешний интерес после публикации релиза.
|
||||
**Почему 2.x, а не v1.x.** Файл имеет смысл, когда есть кому его читать: у
|
||||
проекта один разработчик и внешнего потока PR нет, поэтому сейчас
|
||||
`CONTRIBUTING.md` был бы документом без аудитории и ещё одним местом, где
|
||||
расходится правда о dev loop. Уместен вместе с тем, что реально открывает
|
||||
проект вовне: английская документация процесса (сейчас процессные документы —
|
||||
`progress.md`, `roadmap.md`, `development.md` — на русском, а README и
|
||||
`architecture.md` на английском; для EN-only контрибьютора это барьер) и
|
||||
первый внешний интерес после публикации релиза.
|
||||
|
||||
**Готово, когда:** `CONTRIBUTING.md` в корне описывает dev loop, требования к
|
||||
проверкам перед PR и протокол коммитов; [development.md](development.md) не
|
||||
дублирует его, а ссылается.
|
||||
|
||||
---
|
||||
|
||||
## Разбиение `internal/web` на подпакеты — кандидат на 2.x
|
||||
|
||||
**Что это.** `internal/web` — самый крупный пакет проекта: 47 файлов, ~3030
|
||||
строк, в одной плоскости лежат хендлеры всех разделов панели, сессии,
|
||||
security-заголовки, проверка Origin, валидация форм и рендер шаблонов.
|
||||
Кандидаты на выделение — `web/handlers` и `web/auth`, либо разрез по доменам
|
||||
панели.
|
||||
|
||||
**Почему 2.x, а не сейчас.** На нынешнем размере плоский пакет читается: имена
|
||||
файлов (`handlers_domains.go`, `handlers_apps.go`, `handlers_monitor.go`)
|
||||
работают не хуже каталогов, а разбиение потянуло бы за собой экспорт того, что
|
||||
сейчас пакетно-приватно, — то есть расширение внутреннего API ради
|
||||
косметики. Смысл появляется ровно тогда, когда пакет начнёт расти: обе задачи
|
||||
2.x выше добавляют в него код — роль администратора домена приносит
|
||||
авторизацию в каждый хендлер, входящий релей — отдельные страницы и хендлеры
|
||||
входящих доменов. Рефакторинг дешевле делать перед этим ростом, чем после.
|
||||
|
||||
**Готово, когда:** решение принято осознанно в момент старта 2.x — либо пакет
|
||||
разрезан, либо зафиксировано, что он остаётся плоским.
|
||||
|
||||
Reference in New Issue
Block a user