docs: per-task roadmap, architecture and changelog

- Split TODO into a thin status index plus docs/roadmap/ with one file per
  task (v0.4 reliability, v0.5 product, v0.6 research, icebox).
- Add docs/architecture.md (current processes, packet/data path, layers,
  storage, metrics) and docs/development.md (rules, gates, DoD).
- Add CHANGELOG.md reconstructed from history; move round details out of
  TODO.
- Align docs with the code: config defaults and missing [detect]/
  [protocol.http] sections, XDP metric names, ClickHouse table and TTL,
  Redis RDB restore, multiarch clang include, CLI binary name.
- Add scripts/check_docs_links.sh and run it in CI.
- release profile: thin LTO + one codegen unit. Binary 12.3 MB -> 9.7 MB,
  http parser bench 314 ns -> 278 ns; panic=abort stays off for
  catch_unwind in the Redis subscriber.
- Drop the unused JWT role claim; fix 'rampart doctor' hints in the CLI.
This commit is contained in:
Loki 2026-11-16 14:51:50 +01:00
parent 1b3ae5e546
commit 280284667f
Signed by: boba
GPG key ID: 6CDE87BC9A778D97
38 changed files with 1582 additions and 623 deletions

View file

@ -1,7 +1,8 @@
# Документация Rampart
> Индекс всей документации проекта и правила её ведения.
> Точка входа — [README.md](../README.md); текущий статус и планы — [TODO.md](../TODO.md).
> Точка входа — [README.md](../README.md); текущий статус — [TODO.md](../TODO.md);
> история — [CHANGELOG.md](../CHANGELOG.md).
---
@ -9,9 +10,10 @@
| Документ | Когда читать |
|----------|--------------|
| [architecture.md](architecture.md) | Понять устройство: процессы, путь трафика, слои, хранилища, метрики |
| [deployment.md](deployment.md) | Первый деплой edge-ноды и manager'а |
| [configuration.md](configuration.md) | Настройка `config.toml`, секция `[xdp]`, переменные manager'а |
| [runbook.md](runbook.md) | Ежедневная эксплуатация и типовые операции |
| [configuration.md](configuration.md) | Все поля `config.toml` и переменные окружения Manager |
| [development.md](development.md) | Правила кода, тестов, гейты и Definition of Done |
## 2. Эксплуатация (how-to)
@ -26,41 +28,63 @@
| Документ | О чём |
|----------|-------|
| [configuration.md](configuration.md) | Все поля конфига и значения по умолчанию |
| [api.md](api.md) | HTTP API manager'а: аутентификация, эндпоинты |
| [configuration.md](configuration.md) | Все поля конфига, границы и значения по умолчанию |
| [api.md](api.md) | HTTP API manager'а: аутентификация, эндпоинты, лимиты |
| [vds_compatibility.md](vds_compatibility.md) | Ограничения окружений и ядер |
## 4. Протоколы
## 4. Планы и процесс
| Документ | О чём |
|----------|-------|
| [roadmap/README.md](roadmap/README.md) | Индекс задач по версиям, статусы, правила ведения |
| [roadmap/](roadmap/) | По одному файлу на задачу (v0.4, v0.5, v0.6, icebox) |
| [development.md](development.md) | KISS/DRY/SOLID, лимиты файлов, гейты, anti-patterns |
| [../TODO.md](../TODO.md) | Только текущий статус и ссылки на планы |
| [../CHANGELOG.md](../CHANGELOG.md) | Что и когда изменилось |
## 5. Протоколы
| Документ | О чём |
|----------|-------|
| [minecraft-java.md](minecraft-java.md) | Minecraft-edge: Paper, PROXY protocol, закрытый backend |
## 5. Теория и исследования
## 6. Теория и исследования
| Раздел | О чём |
|--------|-------|
| [kb/](kb/README.md) | База знаний: анатомия атак, уровни защиты, практика (двуязычная) |
| [research/](research/README.md) | Глубокие разборы: архитектура, eBPF, DDoS, Rust-производительность, конкуренты |
`kb/` отвечает на вопрос «как это работает и как защищаться», `research/` — на вопрос
«какое решение выбрать и почему». Статус проекта не живёт ни там, ни там — только в
[TODO.md](../TODO.md).
`kb/` отвечает на вопрос «как это работает и как защищаться», `research/` — на
вопрос «какое решение выбрать и почему». Статус проекта не живёт ни там, ни там —
только в [TODO.md](../TODO.md) и [roadmap/](roadmap/README.md).
---
## 6. Как вести документацию
## 7. Как вести документацию
1. **Язык.** `docs/` — русский. Исключение: [docs/kb/](kb/README.md), где статьи
двуязычные (`## English` / `## Русский`). Комментарии в коде — английский (TODO §0.8).
2. **Один документ = одна задача.** How-to начинается с цели («что получится в конце»),
содержит копируемые команды и заканчивается проверкой результата.
3. **Reference синхронизируется с кодом в том же PR.** Меняешь поле конфига, флаг CLI
или эндпоинт — правишь `configuration.md` / `api.md` там же. Расхождение = баг.
4. **Новый документ** кладётся в подходящую категорию (2–4) и сразу добавляется в эту
таблицу; если он является точкой входа — ссылка добавляется и в корневой README.
5. **Не размножай папки.** Плоская структура `docs/*.md` — норма; подпапка нужна только
для серии документов (`kb/`, `research/`).
6. **Имена файлов** — kebab-case, `.md`, без дат в имени; дата и версия — внутри документа.
7. **Никаких битых ссылок.** Перед коммитом: `grep -o '](\.\?[^)]*)' docs/*.md` и проверь,
что цели существуют.
двуязычные (`## English` / `## Русский`). Комментарии в коде — английский
([development.md](development.md) §5).
2. **Один документ = одна задача.** How-to начинается с цели («что получится в
конце»), содержит копируемые команды и заканчивается проверкой результата.
3. **Reference синхронизируется с кодом в том же PR.** Меняешь поле конфига, флаг
CLI или эндпоинт — правишь `configuration.md` / `api.md` там же. Расхождение =
баг.
4. **Планы не растут в TODO.** Новая задача — новый файл в
[roadmap/](roadmap/README.md); в `TODO.md` добавляется только строка-ссылка.
5. **Новый документ** кладётся в подходящую категорию (1–6) и сразу добавляется в
эту таблицу; если он является точкой входа — ссылка добавляется и в корневой
README.
6. **Не размножай папки.** Плоская структура `docs/*.md` — норма; подпапка нужна
только для серии документов (`kb/`, `research/`, `roadmap/`).
7. **Имена файлов** — kebab-case, `.md`, без дат в имени; дата и версия — внутри
документа.
8. **Никаких битых ссылок.** Перед коммитом: `bash scripts/check_docs_links.sh`
(этот же скрипт работает в CI).
9. **Не дублируй архитектуру.** Схемы и описания слоёв живут в
[architecture.md](architecture.md); остальные документы ссылаются на него.
---
*Версия: 3.0 | Ноябрь 2026*