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, структура модулей
Reference materials	docs/glossary.md, docs/mentor_notes.md	Справочник терминов и заметки для ментора
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-документ снова становится частью основного курса, переноси его обратно в актуальную структуру, а не оставляй полуживой копией.