Make current-course lessons and homework a coherent reading flow

オープン
#425 コメント 5 件 リアクション 0 件 担当者 0 名 GitHub で見る

メンテナーはふだん 1 日以内に返信

まだ誰も着手していません。

評価

難易度
5/5
見積もり時間
1週間以上
初心者へのやさしさ
30/100
issue の種類
機能追加
明瞭さ
明確に書かれている
活発さ
活発
技術スタック
python

調査の方向性

shared_lesson.html、SharedLesson.video_url、既存のUnitの動画表示、およびissueで指定されているshared-curriculumのparser/importとroute、アクセシビリティ、URL/context、cache、sanitization、homeworkのテストから始めます。cohortとarchiveのcontextを含め、モジュールレールをfirst、middle、last、terminal-homeworkの各状態について追跡します。完了とは、対象を絞ったテストとブラウザーシナリオがリグレッションなしでパスし、必要なsource-treeとsyncの証拠が添付されていることです。

索引モデルが issue の本文から書いたものです。

説明

accessibility courses frontend P1

Outcome

Current shared-curriculum reading must behave as one coherent flow: module overview → ordered lessons → cohort-specific terminal homework. Shared lessons must render the structured video_url already imported into SharedLesson.video_url with the same safe, accessible behavior as cohort-bound Unit pages.

The motivating AI Dev Tools lesson currently exposes its recording as an ordinary body link even though video_url is the source contract. The shared importer persists that field, but shared_lesson.html does not render it. Shared lesson navigation is also lesson-only, the homework rail separator is visually broken, the homework is a terminal dead end, and “Open the cohort page →” is vague/redundant.

Normative references:

Product decisions

  • video_url frontmatter is the sole primary-recording field. A recording represented there is removed from body Markdown so it is not shown twice; ordinary topical/external video links remain prose links.
  • Reuse one allowlisted video rendering contract for Unit and SharedLesson: responsive YouTube embed, descriptive title, lazy loading, strict referrer policy, fullscreen/allow policy, and a visible external “Watch on YouTube” fallback. Untrusted/invalid providers are never framed or linked from a corrupt DB value.
  • Navigation is module-local and ends at the selected delivery’s terminal homework. It does not invent cross-module sequencing. When no cohort/homework is resolved, the flow ends at the last lesson and the existing delivery chooser explains how to select a delivery.
  • Homework is a terminal step, not a dead end: it links back to its module and previous lesson, is marked current in the shared rail, and has no false “next” destination.

Scope

Source content
  • Audit current schema-v2 lessons for primary recording body links. For AI Dev Tools, move all four current module recordings into each lesson’s video_url frontmatter and remove only the duplicate body recording line.
  • Preserve lesson ids, paths, titles, navigation frontmatter, body content, and non-primary video links.
  • Prepare and freeze the source changes as an uncommitted, issue-isolated candidate for tester and PM review. Commit/push the byte-identical accepted source tree and perform accepted-SHA sync/import only after both gates, following the lifecycle below.
Shared rendering and flow
  • Give SharedLesson the safe video context and shared player/fallback presentation already expected of Unit.
  • Recompose the module list/rail so lessons and terminal homework read as one ordered surface with continuous borders/separators; remove the curved/dropped dashed seam.
  • Provide coherent controls for module overview, first/middle/last lesson, and terminal homework. Preserve ?cohort=<identifier> on every delivery-dependent link.
  • Mark the current lesson/homework with aria-current="page"; expose ordered-list/list semantics and unambiguous previous/next/back labels.
  • Replace the vague resolved-delivery link with a specific action such as “View 2026 cohort details” only when it adds value; omit it when the page already exposes the relevant delivery action. Preserve chooser and archive-warning states.

Non-goals

  • Cross-module or cross-course next/previous navigation.
  • Changing curriculum order, homework questions/scoring/deadlines, source routes/slugs, canonical URLs, enrollment resolution, archive behavior, or course content beyond duplicate primary-recording links.
  • Supporting arbitrary iframe/video providers or extracting recordings heuristically from rendered Markdown.
  • Hardcoding video/navigation/content in templates or Python outside database-owned fields.
  • Combining #423 or #424 into the same commits/rollback unit.
  • Redesigning legacy/module-format lesson pages beyond extracting a genuinely shared video primitive without visual regression.

Dependencies and coordination

  • Website rendering and source content are implemented and tested together as uncommitted candidates. Issue closure requires an accepted AI Dev Tools source commit and website re-sync, but those release operations occur only after tester and PM gates.
  • The AI Dev Tools working tree had unrelated changes during grooming. Use a clean pinned worktree or coordinate ownership; never stash or overwrite them.
  • #423/#424 are related source changes, not blockers. Rebase/sequence focused commits and verify each SHA independently.

Lifecycle sequencing

  1. Engineering prepares the website diff and the four source lesson edits without committing or pushing either repository, records the pinned source base plus candidate-tree digest, runs the local parser/import twice against that exact candidate, and freezes an issue-isolated handoff.
  2. The independent tester verifies those uncommitted bytes: recomputed selective-CI plan, focused/full required gates, source overlay reconstruction, parser/import/idempotence, and browser/screenshots. An accepted source commit SHA, push, or deployed sync is not a prerequisite for the tester verdict.
  3. PM performs product acceptance on the same frozen uncommitted candidate after tester PASS.
  4. Only after both gates pass, the source owner creates and pushes a focused commit whose tree matches the tested candidate digest exactly. The accepted immutable source SHA is then synced/imported, replayed once more to prove no-op behavior, and its database provenance/render checked.
  5. The website change is committed/merged/pushed under _docs/PROCESS.md; on-call observes required CI and the accepted-SHA content verification. The issue closes only after these post-gate release checks pass.

+Post-gate source commit/push/sync criteria are operations owned after tester/PM acceptance, not pending/skipped components in a tester-final report. Any content or code change beyond attaching the tested bytes to a commit invalidates the gates and returns the work to engineering/tester/PM.

Acceptance criteria

  • Every current AI Dev Tools lesson with a primary recording declares an HTTPS YouTube video_url; the matching body recording link is absent, and non-primary links/content are unchanged.
  • Before tester review, source repository checks and website parser/import tests accept the uncommitted frontmatter together with existing prev_url/next_url; importing the pinned candidate tree twice persists the exact URLs in SharedLesson.video_url and the second local import is a no-op.
  • After tester PASS and PM acceptance, the four source edits are committed/pushed as the byte-identical tested tree. Syncing that immutable accepted SHA persists matching provenance and URLs; a second accepted-SHA sync is a no-op. This post-gate operations criterion is not a precondition of the tester verdict.
  • A shared lesson with an allowed YouTube URL renders one responsive 16:9 player plus a visible external fallback link, with descriptive accessible title, lazy loading, strict referrer policy, allow/fullscreen attributes, and no duplicate recording link in the article.
  • A lesson without video_url renders no player/fallback. An invalid or non-allowlisted stored URL renders neither an iframe nor an unsafe fallback and does not break the page.
  • Cohort-bound Unit and shared SharedLesson use the same video safety/presentation contract and pass parity tests; existing Unit behavior has no visual or security regression.
  • Module overview presents ordered lessons and, when a delivery with terminal homework is resolved, homework as the final distinct step. Borders/separators remain continuous at every radius/theme/width.
  • First lesson offers module context and next lesson; middle lessons offer previous/next; last lesson offers previous and terminal homework when available; terminal homework offers previous lesson and back to module, is visibly/semantically terminal, and has no next control.
  • When no delivery/homework is resolved, no homework link is fabricated and the existing chooser remains. Archive context continues to warn/link to the archive rather than attaching current homework.
  • All module/lesson/homework rail and flow links retain the valid ?cohort= context; canonical URLs remain cohort-query-free. Invalid context keeps existing safe resolution behavior.
  • Current lesson or homework is visibly distinct and carries aria-current="page"; navigation has an accessible name, semantic ordered/list structure, visible focus, ≥44 CSS px targets, and Enter activation.
  • Resolved-delivery copy names the cohort and destination/purpose or is omitted when redundant. “Open the cohort page →” no longer appears as a vague standalone action; chooser/archive states remain clear.
  • At 1440, 768, 390, and 320 CSS px in light/dark mode, video, article, rail, homework seam, and controls have no overlap or document-level overflow. Reduced-motion behavior and focus remain intact.
  • Shared route/canonical/cache behavior, lesson sanitization, imported assets/code links, homework form state/submission, and legacy course pages continue to pass.

Verification scenarios

Repository/service
  1. Run the AI Dev Tools source checker, proving frontmatter/body-link parity and unchanged lesson navigation/content outside the four recording lines.
  2. Run shared curriculum parser/import, shared route, Unit video, homework context/design, URL/context, cache, sanitization, and accessibility tests.
  3. Test allowed YouTube watch/short URLs, no video, malformed URL, and non-allowlisted provider; assert unsafe values never reach iframe/link markup.
  4. Before gates, import the pinned uncommitted candidate tree twice and compare SharedLesson identities, video URLs and rendered body; record its tree digest.
  5. After gates, prove the pushed source commit tree equals that tested digest, sync the accepted SHA twice, and compare identities, URLs, body and persisted provenance.
Browser
  1. With ?cohort=2026, traverse module → first → middle → last lesson → homework using only page controls; then traverse backward. Verify query preservation, labels, current state, and browser history.
  2. Repeat anonymously without a resolved cohort and with archive context; confirm chooser/archive behavior and absence of fabricated homework.
  3. Inspect the player and external fallback with keyboard and a screen reader; confirm one recording presentation and no body duplicate.
  4. Capture module, first/middle/last lesson, and homework at 1440/768/390/320 in both themes, including focus. Verify document.documentElement.scrollWidth === document.documentElement.clientWidth.
  5. Regression-check one cohort-bound Unit video and one legacy homework page.

Evidence to attach

  • Pre-gate AI Dev Tools base/candidate-tree digest and diff summary; after gates, the matching accepted source SHA plus sync provenance/replay output.
  • Focused test results.
  • Desktop/mobile light/dark screenshots of the complete flow, plus video safety/fallback evidence.
主要言語
Python
スター
0
フォーク
0
平均マージ
37分
マージ済み PR(30日)
36

環境構築

  • Dockerfile または Docker Compose ファイルあり
  • プルリクエストのテンプレートなし
  • コントリビューションガイドなし

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

DataTalksClub/website のほかの issue

DataTalksClub/website の issue をすべて見る

似ている issue

Python の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。