ddmitry/clickstream-data-platform
1
0 Fork 0
Code Issues 5 Pull Requests Actions Packages Projects 1 Releases Wiki Activity

Имена файлов docs/labs/: схема S-N-slug #230

New Issue
Closed
opened 2026-09-06 16:03:52 +03:00 by ddmitry · 1 comment
ddmitry commented 2026-09-06 16:03:52 +03:00
Owner
Copy link
Copy source

Part of #206

Цель

Имена файлов в docs/labs/ получают префикс ступени и номера задания: S-N-slug.md. Порядок программы становится виден в каталоге и в ссылках, а не только в таблице README лаб. Решение владельца 2026-09-06 при чтении PR #229: файлов в папке будет много, без номера в них легко запутаться.

Решения

  • Схема — S-N-slug.md, где S — ступень, N — номер задания внутри ступени. Сквозной номер отвергнут: смешивает ступени и задания и сдвигает хвост при вставке. Подпапки по ступеням отвергнуты: лишняя глубина ради одного файла в папке.
  • Факультативы номера не получают: у них нет порядка, остается слаг (superset-dashboard.md).
  • Переименование — через git mv, история файлов сохраняется.
  • Правило имен в AGENTS.md (раздел «Структура», абзац про docs/labs/) переписывается под новую схему тем же PR: номер ступени и задания — часть адреса в программе, а не дата события.

Что переименовать

Было Стало
events-enriched.md 1-1-events-enriched.md
top-pages-daily.md 1-2-top-pages-daily.md
session-overview.md 1-3-session-overview.md
dq-errors-daily.md 1-4-dq-errors-daily.md
utm-effectiveness.md 1-5-utm-effectiveness.md
superset-chart.md 2-1-superset-chart.md

Где поправить ссылки

  • docs/labs/README.md — обе таблицы и ссылка на факультатив.
  • docs/labs/superset-chart.md:9 — ссылка на задание 3.
  • dags/homework_check.py:112–133 — пути к ТЗ в описаниях задач.
  • docs/architecture/dds/session.md:114, docs/architecture/dm.md:50, docs/specs/2026-09-01-labs-program.md:175 — если ссылка ведет на переименованный файл.
  • AGENTS.md — правило имен.

Критерии приемки

  • Шесть файлов переименованы через git mv, git log --follow показывает историю.
  • Скрипт ссылок и якорей из #226 по docs/ печатает пусто; grep -rn по старым именам вне docs/research/ молчит.
  • make lint в корне зеленый (правится dags/homework_check.py).
  • Правило имен docs/labs/ в AGENTS.md описывает схему S-N-slug и исключение для факультативов.

Границы

Содержание ТЗ не трогается. docs/research/ — архив, ссылки там не правятся. Стенд не трогать.

Команды проверки

grep -rn 'labs/\(events-enriched\|top-pages-daily\|session-overview\|dq-errors-daily\|utm-effectiveness\|superset-chart\)\.md\|(\(events-enriched\|top-pages-daily\|session-overview\|dq-errors-daily\|utm-effectiveness\|superset-chart\)\.md' --include=*.md --include=*.py . | grep -v docs/research
make lint
Part of #206 ## Цель Имена файлов в `docs/labs/` получают префикс ступени и номера задания: `S-N-slug.md`. Порядок программы становится виден в каталоге и в ссылках, а не только в таблице README лаб. Решение владельца 2026-09-06 при чтении PR #229: файлов в папке будет много, без номера в них легко запутаться. ## Решения - Схема — `S-N-slug.md`, где `S` — ступень, `N` — номер задания внутри ступени. Сквозной номер отвергнут: смешивает ступени и задания и сдвигает хвост при вставке. Подпапки по ступеням отвергнуты: лишняя глубина ради одного файла в папке. - Факультативы номера не получают: у них нет порядка, остается слаг (`superset-dashboard.md`). - Переименование — через `git mv`, история файлов сохраняется. - Правило имен в AGENTS.md (раздел «Структура», абзац про `docs/labs/`) переписывается под новую схему тем же PR: номер ступени и задания — часть адреса в программе, а не дата события. ## Что переименовать | Было | Стало | |---|---| | `events-enriched.md` | `1-1-events-enriched.md` | | `top-pages-daily.md` | `1-2-top-pages-daily.md` | | `session-overview.md` | `1-3-session-overview.md` | | `dq-errors-daily.md` | `1-4-dq-errors-daily.md` | | `utm-effectiveness.md` | `1-5-utm-effectiveness.md` | | `superset-chart.md` | `2-1-superset-chart.md` | ## Где поправить ссылки - `docs/labs/README.md` — обе таблицы и ссылка на факультатив. - `docs/labs/superset-chart.md:9` — ссылка на задание 3. - `dags/homework_check.py:112–133` — пути к ТЗ в описаниях задач. - `docs/architecture/dds/session.md:114`, `docs/architecture/dm.md:50`, `docs/specs/2026-09-01-labs-program.md:175` — если ссылка ведет на переименованный файл. - `AGENTS.md` — правило имен. ## Критерии приемки - [ ] Шесть файлов переименованы через `git mv`, `git log --follow` показывает историю. - [ ] Скрипт ссылок и якорей из #226 по `docs/` печатает пусто; `grep -rn` по старым именам вне `docs/research/` молчит. - [ ] `make lint` в корне зеленый (правится `dags/homework_check.py`). - [ ] Правило имен `docs/labs/` в AGENTS.md описывает схему `S-N-slug` и исключение для факультативов. ## Границы Содержание ТЗ не трогается. `docs/research/` — архив, ссылки там не правятся. Стенд не трогать. ## Команды проверки ```bash grep -rn 'labs/\(events-enriched\|top-pages-daily\|session-overview\|dq-errors-daily\|utm-effectiveness\|superset-chart\)\.md\|(\(events-enriched\|top-pages-daily\|session-overview\|dq-errors-daily\|utm-effectiveness\|superset-chart\)\.md' --include=*.md --include=*.py . | grep -v docs/research make lint ```
ddmitry added the wayfinder:task label 2026-09-06 16:04:01 +03:00
ddmitry commented 2026-09-06 16:09:38 +03:00
Author
Owner
Copy link
Copy source

Сделано в PR #231.

  • Схема S-N-slug применена к шести ТЗ: 1-1…1-5 для ступени 1, 2-1-superset-chart.md для ступени 2. Факультатив superset-dashboard.md остался под одним слагом.
  • Ссылки поправлены в индексе лаб, в ТЗ ступени 2, в docs/architecture/dds/session.md и в путях dags/homework_check.py. Ссылки на факультатив и docs/research/ не менялись.
  • Правило имен для docs/labs/ в AGENTS.md переписано: номера повторяют порядок программы из README, факультативы без номера.
  • Проверка: make lint, обход относительных ссылок в docs/ и AGENTS.md.

Дальше: новое ТЗ сразу получает имя по схеме, номер берется из таблицы программы в README.

Сделано в PR #231. - Схема `S-N-slug` применена к шести ТЗ: `1-1`…`1-5` для ступени 1, `2-1-superset-chart.md` для ступени 2. Факультатив `superset-dashboard.md` остался под одним слагом. - Ссылки поправлены в индексе лаб, в ТЗ ступени 2, в `docs/architecture/dds/session.md` и в путях `dags/homework_check.py`. Ссылки на факультатив и `docs/research/` не менялись. - Правило имен для `docs/labs/` в AGENTS.md переписано: номера повторяют порядок программы из README, факультативы без номера. - Проверка: `make lint`, обход относительных ссылок в `docs/` и `AGENTS.md`. Дальше: новое ТЗ сразу получает имя по схеме, номер берется из таблицы программы в README.
Sign in to join this conversation.
No Branch/Tag Specified
Labels
Clear labels
needs-info
needs-triage
ready-for-agent
ready-for-human
wayfinder:grilling
wayfinder:map
wayfinder:prototype
wayfinder:research
wayfinder:task
wontfix
No labels wayfinder:task
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
ddmitry (Dmitry Dementiev)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: ddmitry/clickstream-data-platform#230