diff --git a/AGENTS.md b/AGENTS.md index 745e156..8a37f41 100755 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,57 +1,59 @@ # Repository Guidelines -This repository contains a small teaching Lakehouse stack (Spark + Trino + Iceberg + MinIO) intended for demos and mentoring. +Этот репозиторий теперь представляет собой не только локальный Lakehouse-стенд, но и каркас учебного курса `Lakehouse без магии`. -## Project Structure & Module Organization +В `AGENTS.md` держим только стабильные правила для автоматизированных правок. Изменчивый контекст проекта, карта репозитория и правила синхронизации вынесены в [docs/maintainer_guide.md](docs/maintainer_guide.md). -- `docker-compose.yml`: orchestrates Spark, Trino, MinIO, PostgreSQL, and Jupyter. -- `spark/`: Spark image (`Dockerfile`) and `spark-defaults.conf`. -- `jupyter/`: Jupyter image (`Dockerfile`) based on the Spark image. -- `trino/`: catalog config, e.g. `trino/catalog/lakehouse.properties`. -- `src/`: PySpark and SQL examples split by engine (`src/spark/...`, `src/trino/...`). -- `notebooks/`: demo notebooks (mounted into Jupyter at `/opt/work`). -- `plans/`: internal living docs for implementation plans. +## Канонические документы -Keep new examples in `src/` or `notebooks/`, and avoid mixing configuration and code. +- `README.md` — верхнеуровневое описание стенда, архитектуры и сервисов. +- `START_HERE.md` — первый маршрут для студента до запуска ноутбуков. +- `docs/course_prd.md` — рамки курса, learning outcomes, scope и out of scope. +- `docs/course_program.md` — модульная структура курса и состав учебных материалов. +- `docs/maintainer_guide.md` — карта репозитория и правила синхронизации изменений. +- `plans/` — внутренние living docs; не источник истины для студентского маршрута. +- `docs/archive/` — архивные материалы; не использовать как актуальную документацию без явного запроса. -## Build, Test, and Development Commands +## Структура репозитория -Run from the repo root: +- `docker-compose.yml`, `spark/`, `trino/`, `jupyter/` — исполняемый стенд. +- `notebooks/`, `src/` — учебные материалы и вспомогательные примеры. +- `docs/`, `START_HERE.md`, `README.md` — входная и методическая документация. +- `plans/` — внутреннее планирование. -- `docker compose build`: build custom Spark and Jupyter images. -- `docker compose up -d`: start the full stack in the background. -- `docker compose ps`: check container status. -- `docker compose down -v`: stop the stack and remove volumes (for a clean slate). +Новые учебные примеры держи в `src/` или `notebooks/`, а конфигурацию стенда не смешивай с учебным контентом. -Use `docker compose logs -f ` when debugging (`spark-master`, `trino`, `minio`, etc.). +## Правила изменений -## Coding Style & Naming Conventions +- Сначала меняй канонический документ для соответствующего слоя, потом синхронизируй связанные ссылки и упоминания. +- Если меняются сервисы, порты, имена контейнеров, образы или команды запуска, обновляй как минимум `README.md`, `START_HERE.md` и затронутые примеры. +- Если меняются scope курса, learning outcomes или модульная структура, обновляй `docs/course_prd.md` и `docs/course_program.md`, а не только `plans/`. +- Поддерживай согласованный маршрут `README -> START_HERE -> docs/course_program.md -> notebooks/src`. +- Не дублируй крупные фрагменты между документами, если можно сослаться на канонический файл. +- Legacy-материалы явно помечай как архивные и не возвращай их в основной маршрут без явного запроса. -- Python: PEP 8, 4-space indentation, snake_case for functions, lower_snake_case for files (e.g. `spark_join_demo.py`). -- SQL: uppercase keywords, `schema.table` naming, short English identifiers; comments may be in Russian. -- Compose/Docker: service names kebab-case (`spark-master`), env vars UPPER_SNAKE_CASE. -- Prefer small, focused examples; reuse helpers from `src/` in notebooks where possible. +## Стиль и содержание -## Testing Guidelines +- Сохраняй русский язык в student-facing документации, если задача не про перевод. +- Предпочитай небольшие, сфокусированные примеры и не усложняй стенд без явного запроса. +- Держи ноутбуки понятными для самостоятельного прохождения; переиспользуемую логику выноси в `src/`. +- Не добавляй обязательные шаги со скачиванием данных прямо из ноутбуков, если это можно оформить через onboarding-документацию. -There is no formal automated test suite yet. Validate changes by: +## Проверка изменений -- building and starting the stack, then -- running `src/spark/cluster_smoke.py` or the SQL in `src/spark/iceberg_demo.sql`, -- opening `notebooks/01_environment_and_smoke_test.ipynb` in Jupyter and checking it runs end-to-end. +- Для изменений только в документации проверь согласованность ссылок, терминов и маршрута прохождения. +- Для изменений стенда сначала используй лёгкую валидацию вроде `docker compose config`. +- Если меняется поведение стенда или учебных примеров, по возможности проверь сценарии из `src/spark/cluster_smoke.py`, `src/spark/iceberg_smoke.py`, `src/trino/iceberg_smoke.sql` или `notebooks/01_environment_and_smoke_test.ipynb`. +- Если полная проверка не выполнялась, укажи это явно. -If you add tests, prefer `pytest` under `tests/` and mark slow, integration-heavy tests clearly. +## Commit & PR Notes -## Commit & Pull Request Guidelines - -- Commits: short, descriptive subject in Russian or English, present tense (e.g. `Спарк запускается, создаётся тестовая таблица`, `Add Iceberg join demo`). -- Keep changes small and focused; update `README.md` when behavior, ports, or images change. -- PRs should describe the problem, the solution, and any impact on local setup; include screenshots (Trino UI, MinIO, Jupyter) when UI changes are relevant. +- Коммиты: короткий subject в настоящем времени, на русском или английском. +- Изменения поведения, портов, маршрута входа или состава материалов обычно требуют обновления документации рядом с кодом. +- Избегай больших рефакторингов структуры без явного запроса пользователя. ## Agent-Specific Instructions -When editing as an automated agent: - -- Respect this file and avoid large refactors without an explicit request. -- Preserve Russian user-facing text unless the change is explicitly about translation. -- Prefer minimal changes that keep the demo simple and robust for newcomers. +- Уважай существующие изменения пользователя и не откатывай их без запроса. +- Предпочитай минимальные изменения, которые делают курс проще и устойчивее для новичка. +- Если непонятно, какой маршрут сейчас актуален, доверяй `START_HERE.md` и `docs/course_program.md`, а не старым HOWTO или планам. diff --git a/docs/maintainer_guide.md b/docs/maintainer_guide.md new file mode 100644 index 0000000..52b6f79 --- /dev/null +++ b/docs/maintainer_guide.md @@ -0,0 +1,108 @@ +# Карта репозитория и источники истины + +Этот документ нужен, чтобы не раздувать `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` | Вход в стенд и первый пользовательский маршрут | +| 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 во всех деталях | +| `START_HERE.md` | Первый маршрут студента: prerequisites, запуск, первые UI, первый ноутбук, базовая диагностика | Полный PRD курса или подробный бэклог модулей | +| `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`; +- затронутые команды в `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-документ снова становится частью основного курса, переноси его обратно в актуальную структуру, а не оставляй полуживой копией.