ddadmin
3f76d66ed1
- Зачем: - нужно убрать смешение маршрута студента с внутренними документами сопровождения репозитория. - Что: - переработан README.md как верхнеуровневый вход в репозиторий без ссылок на внутренние maintainer-документы. - добавлен docs/stack_reference.md для технического reference стенда и уточнены его роли относительно START_HERE.md. - синхронизированы AGENTS.md и docs/maintainer_guide.md под новую границу между onboarding и внутренней документацией. - Проверка: - сверены README.md, START_HERE.md, docs/stack_reference.md, AGENTS.md и docs/maintainer_guide.md на согласованность маршрута и аудиторий.
61 lines
6.0 KiB
Markdown
Executable File
61 lines
6.0 KiB
Markdown
Executable File
# Repository Guidelines
|
||
|
||
Этот репозиторий теперь представляет собой не только локальный Lakehouse-стенд, но и каркас учебного курса `Lakehouse без магии`.
|
||
|
||
В `AGENTS.md` держим только стабильные правила для автоматизированных правок. Изменчивый контекст проекта, карта репозитория и правила синхронизации вынесены в [docs/maintainer_guide.md](docs/maintainer_guide.md).
|
||
|
||
## Канонические документы
|
||
|
||
- `README.md` — верхнеуровневое описание репозитория, архитектуры и точек входа.
|
||
- `START_HERE.md` — первый маршрут для студента до запуска ноутбуков.
|
||
- `docs/stack_reference.md` — технический reference по сервисам, портам, доступу и smoke-тестам.
|
||
- `docs/course_prd.md` — рамки курса, learning outcomes, scope и out of scope.
|
||
- `docs/course_program.md` — модульная структура курса и состав учебных материалов.
|
||
- `docs/maintainer_guide.md` — карта репозитория и правила синхронизации изменений.
|
||
- `plans/` — внутренние living docs; не источник истины для студентского маршрута.
|
||
- `docs/archive/` — архивные материалы; не использовать как актуальную документацию без явного запроса.
|
||
|
||
## Структура репозитория
|
||
|
||
- `docker-compose.yml`, `spark/`, `trino/`, `jupyter/` — исполняемый стенд.
|
||
- `notebooks/`, `src/` — учебные материалы и вспомогательные примеры.
|
||
- `docs/`, `START_HERE.md`, `README.md` — входная и методическая документация.
|
||
- `plans/` — внутреннее планирование.
|
||
|
||
Новые учебные примеры держи в `src/` или `notebooks/`, а конфигурацию стенда не смешивай с учебным контентом.
|
||
|
||
## Правила изменений
|
||
|
||
- Сначала меняй канонический документ для соответствующего слоя, потом синхронизируй связанные ссылки и упоминания.
|
||
- Если меняются сервисы, порты, имена контейнеров, образы или команды запуска, обновляй как минимум `README.md`, `START_HERE.md`, `docs/stack_reference.md` и затронутые примеры.
|
||
- Если меняются scope курса, learning outcomes или модульная структура, обновляй `docs/course_prd.md` и `docs/course_program.md`, а не только `plans/`.
|
||
- Поддерживай согласованный маршрут `README -> START_HERE -> docs/course_program.md -> notebooks/src`.
|
||
- Не дублируй крупные фрагменты между документами, если можно сослаться на канонический файл.
|
||
- Legacy-материалы явно помечай как архивные и не возвращай их в основной маршрут без явного запроса.
|
||
|
||
## Стиль и содержание
|
||
|
||
- Сохраняй русский язык в student-facing документации, если задача не про перевод.
|
||
- Предпочитай небольшие, сфокусированные примеры и не усложняй стенд без явного запроса.
|
||
- Держи ноутбуки понятными для самостоятельного прохождения; переиспользуемую логику выноси в `src/`.
|
||
- Не добавляй обязательные шаги со скачиванием данных прямо из ноутбуков, если это можно оформить через onboarding-документацию.
|
||
|
||
## Проверка изменений
|
||
|
||
- Для изменений только в документации проверь согласованность ссылок, терминов и маршрута прохождения.
|
||
- Для изменений стенда сначала используй лёгкую валидацию вроде `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`.
|
||
- Если полная проверка не выполнялась, укажи это явно.
|
||
|
||
## Commit & PR Notes
|
||
|
||
- Коммиты: короткий subject в настоящем времени, на русском или английском.
|
||
- Изменения поведения, портов, маршрута входа или состава материалов обычно требуют обновления документации рядом с кодом.
|
||
- Избегай больших рефакторингов структуры без явного запроса пользователя.
|
||
|
||
## Agent-Specific Instructions
|
||
|
||
- Уважай существующие изменения пользователя и не откатывай их без запроса.
|
||
- Предпочитай минимальные изменения, которые делают курс проще и устойчивее для новичка.
|
||
- Если непонятно, какой маршрут сейчас актуален, доверяй `START_HERE.md` и `docs/course_program.md`, а не старым HOWTO или планам.
|