docs(course): add development roadmap and issue links

2026-09-15 07:16:19 -04:00
1 parent 34a3cb309c
commit ff474f05f6
@@ -42,6 +42,8 @@
 | `plans/` | Внутренний статус работ, живые планы, декомпозиция задач | Источник истины для student-facing маршрута |
 | `docs/archive/` | Справочный legacy-контент | Актуальные инструкции без явной пометки `legacy` |

+Отзывы студентов и порядок следующих доработок собраны в [плане развития курса](../plans/course-roadmap.md). Подробные задания и текущий статус исполнения ведутся в [Gitea Issues](https://git.dementev.space/ddmitry/mini-lakehouse-lab/issues); правила работы с трекером описаны в [issue-tracker.md](./agents/issue-tracker.md).
+
 ## Порядок приоритетов, если документы расходятся

 - Для реального поведения стенда: `docker-compose.yml` и runtime-конфиги важнее `README.md`.
@@ -2,14 +2,20 @@

 Этот каталог хранит внутренние рабочие планы по развитию учебного курса.

+## Развитие после первой версии
+
+[План развития курса](./course-roadmap.md) — отзывы студентов, ближайшие доработки, их порядок и ссылки на задачи в Gitea.
+
 ## Правила хранения

 - Формат: `living docs`.
 - История изменений хранится в git.
- Именование файлов: `module-NN-<english-slug-from-module-title>.md`.
+- Именование планов отдельных модулей: `module-NN-<english-slug-from-module-title>.md`.
 - В каждом плане фиксируются `Статус` и `Последнее обновление`.

-## Оглавление
+## Планы разработки модулей первой версии
+
+Ниже сохранены планы разработки восьми модулей. Их статусы отражают записи в этих документах; актуальный маршрут прохождения описан в [программе курса](../docs/course_program.md).

 | Модуль | План | Статус | Целевые артефакты | Обновлён |
 | --- | --- | --- | --- | --- |
@@ -0,0 +1,81 @@
+# План развития курса «Lakehouse без магии»
+
+Статус: ближайшие доработки определены, реализация впереди.
+Последнее обновление: 2026-09-15.
+
+Здесь собираем отзывы студентов, выбираем следующие улучшения и объясняем их порядок. Подробные задания, критерии приёмки и актуальный статус исполнения хранятся в [Gitea Issues](https://git.dementev.space/ddmitry/mini-lakehouse-lab/issues).
+
+Текущие рамки курса задаёт [PRD](../docs/course_prd.md), а состав уроков — [программа](../docs/course_program.md). Запись в этом плане означает будущую работу. При реализации изменения сначала обновляем соответствующий канонический документ, затем учебные материалы и ссылки на них.
+
+## Обратная связь
+
+### Базовая настройка Spark-сессии
+
+- **Источник:** отзыв Арсения Деева, переданный автором курса и зафиксированный 2026-09-15. На момент отзыва студент дошёл до модуля 4.
+- **Наблюдение студента:** курс подходит начинающим, но не хватает базовой настройки Spark-сессии без сложного тюнинга.
+- **Учебный пробел:** студент использует подготовленную сессию; ему нужна практика, чтобы понять, какие настройки потребуются вне готового ноутбука.
+- **Решение:** добавить короткую обязательную практику после модуля 2, перед работой с raw-данными в модуле 3. До её разработки проверить воспроизводимость создания сессий.
+
+Отзыв относится к уже пройденной части курса. Замечания по модулям 5–8 пока не получены.
+
+## Ближайшие работы
+
+### 1. Проверить и исправить создание Spark-сессий
+
+**Статус:** запланировано; выполняется первым.
+
+**Задача:** [#1 — подключение Spark-сессий в новом ядре](https://git.dementev.space/ddmitry/mini-lakehouse-lab/issues/1).
+
+В `src/spark/cluster_smoke.py` адрес master задаётся явно. В модуле 2 комментарий говорит, что master берётся из `spark-defaults.conf`, однако в этом файле нет `spark.master`. В модулях 2–8 сессия создаётся без явного `.master(...)`. Это подтверждённое расхождение исходников; фактический режим работы этих ноутбуков в новом ядре ещё не проверен.
+
+Нужно проверить создание сессии каждого ноутбука в отдельном новом ядре, зафиксировать фактический master и привести код и пояснения к воспроизводимому способу подключения. Повторное прохождение сохраняет учебные данные из предыдущих модулей: независимость от состояния ядра не означает независимость от этих данных.
+
+**Результат:** каждый ноутбук подключается к ожидаемому Spark-кластеру после перезапуска ядра; документация правильно объясняет источник настроек. Проверки и необходимые исправления описываются в задаче.
+
+### 2. Добавить практику «Как настроен Spark в нашем стенде»
+
+**Статус:** запланировано; зависит от результата работы 1.
+
+**Задача:** [#2 — практика базовой настройки SparkSession](https://git.dementev.space/ddmitry/mini-lakehouse-lab/issues/2), заблокирована задачей #1.
+
+Практику разместить в начале модуля 3. Ориентир — 20–30 минут; фактическую длительность проверить при прохождении.
+
+Студент должен научиться:
+
+- объяснять роли `SparkSession`, `SparkContext`, driver и executors на примере стенда;
+- читать код с `master`, `appName` и `getOrCreate`;
+- находить источник настройки: конфигурационный файл, параметры запуска или код;
+- проверять фактический master и выбранные настройки каталога Iceberg и MinIO;
+- различать настройки, меняемые во время работы, и настройки, требующие нового запуска;
+- понимать, что повторное выполнение ячейки может использовать уже существующую сессию.
+
+**Практика и checkpoint:** студент заполняет небольшой шаблон создания сессии, задаёт подключение к кластеру и имя приложения, использует подготовленные настройки каталога, проверяет фактическое подключение и читает небольшую учебную Iceberg-таблицу. Таблица должна создаваться самой практикой: демонстрационные таблицы модуля 2 могут быть удалены при его завершении. Студент объясняет, какие настройки он задал сам, какие предоставил стенд и что потребуется повторить в новом ядре.
+
+При реализации обновить learning outcomes и scope в PRD, содержание и checkpoint модуля 3 в программе, ноутбук и связанные справочные материалы. Сохранить структуру из восьми модулей.
+
+**Граница темы:** базовая настройка подключения и жизненный цикл сессии. Подробный подбор памяти, числа executors, shuffle и GC остаётся за рамками этой доработки.
+
+### 3. Собрать замечания по оставшейся части курса
+
+**Статус:** ожидается продолжение обратной связи.
+
+По мере прохождения Арсением остальных модулей добавлять конкретные наблюдения в этот документ. После полного прохода выбрать следующие доработки с учётом повторяющихся затруднений, самостоятельности студента и общей длительности курса.
+
+Новые issues создавать, когда понятны проблема, ожидаемый результат и способ его проверки.
+
+## Отложенные идеи
+
+- Небольшой дополнительный опыт с числом партиций и наблюдением выполнения в Spark UI. Вернуться к нему после проверки объёма базовой практики; потребуется объяснить распределённое выполнение.
+- Другие возможные расширения перечислены в [разделе 7 программы](../docs/course_program.md#7-что-не-входит-в-первую-версию-курса). Их включение и порядок пока не определены.
+
+Номер и дата следующего релиза пока не назначены.
+
+## Как обновлять этот план
+
+Для нового предложения записывать: источник и этап прохождения → наблюдение → учебный пробел → предлагаемое изменение → проверяемый результат → статус и ссылка на issue.
+
+После реализации добавлять ссылку на итог задачи и кратко отмечать, что изменилось для студента. Подробные критерии и ход исполнения сохранять в issue.
+
+## Выпущенные улучшения
+
+Доработки из этого плана ещё не выпущены.