mini-lakehouse-lab/docs/maintainer_guide.md

# Карта репозитория и источники истины

Этот документ нужен, чтобы не раздувать `AGENTS.md` и не дублировать изменчивый контекст проекта в нескольких местах.

Это внутренний документ сопровождения репозитория. Для прохождения курса и первого запуска стенда он обычно не нужен.

## Что это за репозиторий сейчас

Репозиторий состоит из двух тесно связанных слоёв:

1. Локальный Lakehouse-стенд на `Spark + Trino + Iceberg + MinIO + PostgreSQL`.
2. Учебный курс `Lakehouse без магии`, который использует этот стенд как практическую среду.

Из-за этого изменения часто затрагивают не только конфиги и контейнеры, но и маршрут студента по документации и ноутбукам.

## Основные зоны репозитория

| Зона | Где лежит | Назначение |
| --- | --- | --- |
| Runtime / stand | `docker-compose.yml`, `spark/`, `trino/`, `jupyter/` | Топология сервисов, образы, конфиги, порты |
| Onboarding | `README.md`, `START_HERE.md` | Вход в репозиторий и первый пользовательский маршрут |
| Runtime reference | `docs/stack_reference.md` | Технические детали стенда: порты, доступ, команды, smoke-тесты |
| Course definition | `docs/course_prd.md`, `docs/course_program.md` | Границы курса, learning outcomes, структура модулей |
| Practice materials | `notebooks/`, `src/` | Практика студента, smoke-скрипты, демонстрации, helper-логика |
| Internal planning | `plans/` | Внутренние living docs по разработке материалов |
| Archive | `docs/archive/` | Исторические материалы, не входящие в актуальный маршрут |

## Источники истины

| Файл или каталог | За что отвечает | Что не стоит туда складывать |
| --- | --- | --- |
| `docker-compose.yml` | Реальный состав сервисов, контейнеров, сетей, портов и зависимостей | Учебные пояснения, которые не нужны для запуска |
| `spark/`, `trino/`, `jupyter/` | Конкретные runtime-конфиги и образы | Описание программы курса |
| `README.md` | Верхнеуровневое объяснение репозитория, архитектуры и точек входа | Пошаговый student onboarding во всех деталях и low-level runtime reference |
| `START_HERE.md` | Первый маршрут студента: prerequisites, запуск, первые UI, первый ноутбук, базовая диагностика | Полный PRD курса или подробный бэклог модулей |
| `docs/stack_reference.md` | Технический reference стенда: сервисы, порты, доступ, reset, smoke-тесты | Роль основного onboarding-документа или описание всей программы курса |
| `docs/course_prd.md` | Product scope, аудитория, learning outcomes, dataset strategy, out of scope | Технические мелочи запуска контейнеров |
| `docs/course_program.md` | Модульная структура курса, состав материалов, checkpoints | Подробные docker-команды и legacy-лабы |
| `notebooks/` | Каноническая практическая часть курса | Длинные инфраструктурные HOWTO |
| `src/` | Smoke-скрипты, SQL-демо и переиспользуемая helper-логика | Случайные одноразовые заметки и черновики |
| `plans/` | Внутренний статус работ, живые планы, декомпозиция задач | Источник истины для student-facing маршрута |
| `docs/archive/` | Справочный legacy-контент | Актуальные инструкции без явной пометки `legacy` |

## Порядок приоритетов, если документы расходятся

- Для реального поведения стенда: `docker-compose.yml` и runtime-конфиги важнее `README.md`.
- Для первого student onboarding: `START_HERE.md` важнее старых HOWTO и внутренних планов.
- Для scope курса: `docs/course_prd.md` важнее `plans/`.
- Для структуры модулей и состава практик: `docs/course_program.md` важнее случайных упоминаний в README или archive-документах.

Если после изменения документы начинают спорить друг с другом, исправляй не только тот файл, который менял, но и ближайший канонический слой.

## Что обновлять при разных типах изменений

### Если меняется стенд

Примеры: новые сервисы, другие порты, переименование контейнеров, изменения образов, новые обязательные env vars.

Минимум проверь и при необходимости обнови:

- `docker-compose.yml`;
- `README.md`;
- `START_HERE.md`;
- `docs/stack_reference.md`;
- затронутые команды в `src/`, ноутбуках и планах.

### Если меняется маршрут студента

Примеры: новый первый ноутбук, другой onboarding-flow, перенос шагов из README в отдельный документ.

Минимум проверь и при необходимости обнови:

- `START_HERE.md`;
- `docs/course_program.md`;
- соответствующие `notebooks/`;
- `README.md`, если меняется верхнеуровневый вход в репозиторий.

### Если меняется scope курса

Примеры: новый обязательный модуль, изменение learning outcomes, перенос темы в backlog, смена основного датасета.

Минимум проверь и при необходимости обнови:

- `docs/course_prd.md`;
- `docs/course_program.md`;
- релевантные `plans/`;
- student-facing материалы, если scope уже отражён в них явно.

### Если добавляется новый учебный материал

Примеры: новый ноутбук, новый smoke-скрипт, новый SQL demo.

Обычно нужно:

- положить практику в `notebooks/` или `src/`;
- отразить её в `docs/course_program.md`, если материал входит в основной трек;
- при необходимости обновить `START_HERE.md`, если это новая точка входа;
- не раздувать `README.md` подробностями модуля, если это уже описано в программе курса.

## Что не стоит держать в AGENTS.md

- Полную программу курса по модулям.
- Подробные таблицы портов и runtime-параметров.
- Длинные HOWTO и лабораторные сценарии.
- Исторические объяснения того, как стенд выглядел раньше.

`AGENTS.md` должен оставаться коротким набором правил. Всё, что часто меняется вместе с курсом и стендом, лучше хранить в обычной документации.

## Работа с legacy-материалами

- `docs/archive/` хранит полезный контекст, но не определяет текущий маршрут курса.
- Если старый материал нужен как reference, оставляй его в archive и явно помечай, почему он не канонический.
- Если legacy-документ снова становится частью основного курса, переноси его обратно в актуальную структуру, а не оставляй полуживой копией.