# cs-video-courses Administrator & Developer Guide > **Audience:** maintainers, contributors who want to understand the project's structure and policy, and people forking the list to build a domain-specific variant (e.g. `data-science-video-courses`, a departmental syllabus, or a security-courses fork). --- ## 1. Architecture Overview `Developer-Y/cs-video-courses` is a **content repository**, not a runtime. It has: - **Three tracked files**: `README.md`, `NOTES.md`, `CONTRIBUTING.md`. - **No build step, no CI, no tests, no code, no dependencies.** - **One surface**: the 1,596-line `README.md` containing ~748 catalog entries. - **A single maintainer** who reviews and merges pull requests. Its "product" is a curated, copy-editable, plain-text index of university CS courses with freely available lecture video. The project's value derives entirely from editorial policy and community contribution discipline — there is nothing to deploy, nothing to ship, and nothing to break at runtime. ```text cs-video-courses/ ├── README.md ← the catalog (1596 lines, ~43 categories, ~748 entries) ├── NOTES.md ← policy notes for readers (12 lines) └── CONTRIBUTING.md ← contributor policy (5 lines) ``` That is the whole system. No sub-directories, no data files, no scripts, no configs. > [!NOTE] > The single-README structure is deliberate, not accidental. Several more elaborate architectures were considered and explicitly rejected. See the "Why the repo is structured this way" section before proposing structural changes. ### What this means operationally | Concern | Status in this repo | |---|---| | Build system | None. | | CI / CD | None (beyond GitHub's default). | | Tests | None. | | Dependencies | None. | | Runtime | Browser rendering of markdown — GitHub provides it for free. | | Secrets / config | None. | | Security surface | Malicious links or prompt-injection payloads can be added via PR. See Security section. | | Infrastructure | GitHub hosting only. | ### Why the repo is structured this way The format is deliberate. The maintainer rejected several structures commonly proposed by contributors and imitators: 1. **Per-topic files** (`machine-learning.md`, `algorithms.md`). Rejected: breaks in-page search and makes cross-topic navigation slower. 2. **A JSON/YAML database + generator script.** Rejected: adds a build step, makes PRs harder to review, and loses the "one scroll" skim experience. 3. **A separate website.** Rejected: GitHub renders markdown adequately, adds in-page search, supports outline navigation, and keeps the edit surface trivial. 4. **Descriptions and ratings.** Rejected in `NOTES.md`: they do not scale, invite bike-shedding, and triple the file size. Understanding these rejections is important before proposing structural changes in issues or PRs. --- ## 2. The Maintenance Model ### Single-maintainer, PR-driven - The repo is owned by a single GitHub user (`Developer-Y`). - All changes arrive as pull requests against `master`. - The maintainer manually reviews and merges — there are no triage bots, no required reviewers beyond the owner, and no automated link-health checks. ### Expected throughput Because review is manual, merge latency varies with the maintainer's availability. Contributors should: - Keep PRs small (ideally one category's worth of additions per PR). - Match the surrounding formatting exactly — reduces review time to seconds. - Cite the university and course level in the PR description when the entry itself is ambiguous. ### Spam policy `README.md` explicitly states: > Please feel free to raise any genuine issue you may have, however, it has been noticed that few people open empty issues to raise their GitHub contribution on their account. Such spammers will be blocked. This is operationally enforced: the maintainer blocks users who open empty issues for contribution-count padding. When triaging, do not treat empty issues as legitimate tickets. > [!WARNING] > Do not attempt to use issue-filing as a way to boost GitHub contribution counts. The maintainer actively monitors for this pattern and blocks offending accounts. --- ## 3. Contribution Contract The full contract lives in three files. ### Inclusion criteria (`CONTRIBUTING.md`) | Criterion | Accept | Reject | |---|---|---| | Length | Full-semester course with comprehensive lecture material | 4–5 hour MOOC that skims a topic | | Link type | Direct video (YouTube, OCW, university page) | Paywalled or registration-gated platforms | | Academic level | University undergraduate or graduate | Bootcamp, tutorial, YouTube-channel promo | | Level ordering | Undergrad → upper-undergrad → graduate within a category | (order enforced by reviewer) | ### Entry format (`NOTES.md`) ```text - [ ]() ([Video Playlist]()) ``` - Metadata is encoded **in the link text**, not as separate columns. - Secondary links (video playlists, lecture notes, assignment archives) appear in parentheses after the primary link. - No bold, no italics, no callouts, no images. > [!IMPORTANT] > Matching the entry format exactly is not optional. Reviewers reject or request changes on PRs with misformatted entries. Copy the format from a neighboring entry in the same category. ### Takedown policy Professors whose courses are listed can have them removed: 1. Professor opens a PR removing their course line from `README.md`. 2. PR description states ownership and removal intent. 3. Maintainer reviews and merges (no proof-of-identity required). This policy is documented in `NOTES.md`. It exists because most links come from public OCW sites, but the list honors individual professors' wishes even when the underlying material is legally available elsewhere. --- ## 4. Category Design ### Current category list The README groups entries into 43 categories (27 top-level `##` headings, 26 sub-categories as `###` headings): 1. Introduction to Computer Science 2. Data Structures and Algorithms 3. Math for Computer Scientist 4. Systems Programming: Operating Systems 5. Systems Programming: Distributed Systems 6. Systems Programming: Real-Time Systems 7. Database Systems 8. Software Engineering: Object Oriented Design 9. Software Engineering: Software Engineering 10. Software Engineering: Software Architecture 11. Software Engineering: Concurrency 12. Software Engineering: Mobile Application Development 13. Artificial Intelligence 14. Machine Learning: Introduction to Machine Learning 15. Machine Learning: Data Mining 16. Machine Learning: Probabilistic Graphical Modeling 17. Machine Learning: Deep Learning 18. Machine Learning: Reinforcement Learning 19. Machine Learning: Advanced Machine Learning 20. Machine Learning: Natural Language Processing 21. Machine Learning: Generative AI and LLMs 22. Machine Learning: Computer Vision 23. Machine Learning: Time Series Analysis 24. Machine Learning: Optimization 25. Machine Learning: Unsupervised Learning 26. Machine Learning: Misc Machine Learning Topics 27. Computer Networks 28. Web Programming and Internet Technologies 29. Theoretical CS and Programming Languages 30. Embedded Systems 31. Real time system evaluation 32. Computer Organization and Architecture 33. Security 34. Computer Graphics 35. Image Processing and Computer Vision 36. Computational Physics 37. Computational Biology 38. Quantum Computing 39. Robotics and Control 40. Computational Finance 41. Network Science 42. Blockchain Development 43. Misc ### Design choices worth knowing - **Nested categories** (`Software Engineering > Concurrency`, `Machine Learning > Deep Learning`) are rendered as `H3` headings, while top-level categories are `H2`. This hierarchy is honored by GitHub's outline panel. - **"Generative AI and LLMs" was added separately from "Deep Learning"** to keep the deep-learning section stable as LLM-specific courses proliferate. Treat this split as permanent. - **"Math for Computer Scientist" is a single category** covering discrete math, linear algebra, probability, and information theory. Subdivision has been discussed in issues and rejected as overkill for current volume. - **"Misc" is a real category**, not a dumping ground. It holds courses that genuinely do not fit the other 42 buckets (philosophy of CS, history, cross-disciplinary seminars). ### When to propose a new category **Acceptable signals:** - Five or more new entries that do not fit any existing category without stretching the fit. - A recognized subfield with distinct pedagogy from its parent (the LLMs split is precedent). **Unacceptable signals:** - A single niche course — put it in the closest existing fit. - A trending industry topic with no settled academic curriculum — wait until multiple universities offer full-semester courses. --- ## 5. Security The repository has a small but non-zero security surface distinctive to content-only repos. ### Threat model 1. **Malicious link insertion via PR.** An attacker opens a PR that looks like a legitimate course entry but links to malware, phishing, or tracking redirectors. **Mitigation:** Manual review of every PR. Prefer well-known university domains (`mit.edu`, `stanford.edu`, `berkeley.edu`) and major video hosts (`youtube.com`, `vimeo.com`). Treat shortened URLs (`bit.ly`, `t.co`, `tinyurl.com`, `lnkd.in`) as immediate rejection signals — they hide the destination. 2. **Prompt-injection payloads in link text.** Because the README is increasingly consumed by LLM agents, an attacker could embed instructions in bullet text designed to hijack downstream agent behavior. **Mitigation:** Every bullet should describe a real course. Reject unusual formatting, unusual Unicode, zero-width characters, or instruction-like sentences in a bullet. 3. **Invisible Unicode in link text.** Soft hyphens (`U+00AD`), zero-width spaces (`U+200B`), right-to-left overrides (`U+202E`), and bidi-control characters can be inserted into apparently normal text, invisible in the GitHub viewer but disruptive to automated tooling. **Mitigation:** Review PRs in a plain-text editor that highlights non-printable characters. Run a targeted grep: ```bash grep -nP '[\x{00AD}\x{200B}-\x{200D}\x{202A}-\x{202E}\x{FEFF}]' README.md ``` 4. **Link rot and silent replacement.** An entry that points at a legitimate URL today can be replaced by the upstream owner with something unwanted. **Mitigation:** Periodic link-health audits. Dead links become broken-link issues; replaced-content links rely on community reports. > [!CAUTION] > LLM-agent consumption of the README is a real attack vector for prompt-injection. Reviewers should treat any bullet that contains imperative instructions, unusual Unicode, or non-course content as a potential injection attempt and reject the PR immediately. ### What this repo does NOT need - Dependency vulnerability scanning (no dependencies). - SAST / DAST (no code). - Secret scanning (no build artifacts — but leave GitHub's built-in secret scanning enabled; it runs free on markdown). - Container scanning (no containers). --- ## 6. Operations ### Keeping the catalog healthy A maintainer can run these lightweight checks periodically. None are wired as CI, but all are straightforward one-liners. **Count entries per category:** ```bash awk '/^## /{cat=$0; next} /^### /{cat=cat" > "$0; next} /^- \[/{count[cat]++} END{for (c in count) printf "%4d %s\n", count[c], c}' README.md | sort -rn ``` **Find duplicate course numbers across categories** (legitimate cross-lists exist, but surprises are worth reviewing): ```bash grep -oE '\b(CS|COMP|EECS|6\.[0-9]+|15-[0-9]+|18\.[0-9]+)[ -]?[0-9A-Z]*' README.md | sort | uniq -c | sort -rn | head -20 ``` **Find link-shortener URLs** (should almost never appear): ```bash grep -oE 'https?://(bit\.ly|t\.co|tinyurl\.com|lnkd\.in|goo\.gl)/[^ )\]]+' README.md ``` **Find invisible Unicode** (security hygiene): ```bash grep -nP '[\x{00AD}\x{200B}-\x{200D}\x{202A}-\x{202E}\x{FEFF}]' README.md ``` **Find malformed entries** (missing URL, unclosed bracket, etc.): ```bash grep -nE '^- \[[^]]*$' README.md # unterminated link text grep -nE '^- [^[]' README.md # entry without a link at all ``` > [!TIP] > Run the malformed-entry checks before merging any large batch PR. Contributors occasionally miss a closing bracket or paste without the link, and the issue is invisible in GitHub's rendered view. ### Link-health sweep No link-checker runs automatically. For a periodic sweep, any of the following work against the README without special configuration: | Tool | Install | Run | |---|---|---| | `lychee` | `cargo install lychee` | `lychee README.md --max-concurrency 8 --timeout 20` | | `markdown-link-check` | `npm i -g markdown-link-check` | `markdown-link-check README.md` | | `urlchecker` (Python) | `pip install urlchecker` | `urlchecker check README.md` | Dead links are expected to accumulate over time as university course pages rotate. A quarterly sweep and targeted PRs to fix the highest-value dead links is sufficient. > [!NOTE] > `lychee` is the most maintainer-friendly option for this repo: it respects `robots.txt`, handles rate-limiting gracefully, and outputs per-URL status in a clean table. Use `--exclude-mail` to skip any `mailto:` links that appear in `CONTRIBUTING.md`. ### GitHub-side operations - **Branch protection**: enforce on `master` (require PR, block force pushes). The default GitHub rules are sufficient; no environment-specific settings are needed. - **Issue templates**: optional. A template prompting for category, course number, source URL, and level reduces back-and-forth in triage. - **Pull request templates**: also optional; a template asking for university, course number, level, and video-accessibility check is useful. --- ## 7. Forking the List Forking to a domain variant (`data-science-video-courses`, `security-video-courses`, a departmental syllabus, etc.) is a common use case. ### What to keep - The single-README-with-categories structure. - The no-descriptions policy (description-free scales; description-full does not). - The "direct video only" link policy. - The entry format with metadata embedded in link text. ### What to change - The category set. A data-science fork collapses the Software Engineering tree and expands Machine Learning. - The categories' ordering. Different audiences want different defaults. - The inclusion criteria. A "short courses" fork may legitimately want 3–5 hour MOOCs, in which case `CONTRIBUTING.md` should reflect the change. ### What to communicate clearly - Whose fork this is and why it diverged. - What the new inclusion policy is. - A link back to the upstream list for breadth. ### Merging upstream changes When upstream adds a category your fork also wants, merging is trivial — markdown merges cleanly. When upstream adds a category you do not want, skip it. There is no binary compatibility concern; a markdown fork is free to diverge arbitrarily. --- ## 8. Statistics & Scale As of commit `fcd263d` (2026-04-12): | Metric | Value | |---|---| | Tracked files | 3 | | Total lines in `README.md` | 1,596 | | Entries (lines starting with `- [`) | 748+ | | Top-level categories (`##`) | 27 | | Sub-categories (`###`) | 26 | | Total categories including sub-categories | ~43 | | License | Not explicitly stated (contributions treated as MIT-compatible by convention; verify before forking commercially) | | Repo size | Under 500 KB | These numbers will drift with each merged PR. They are useful baselines for noticing rapid growth (which might signal spam PRs) or rapid shrinkage (bulk removals). --- ## 9. Known Issues & Tech Debt 1. **Professors' takedown process is PR-based.** A professor who wants their course removed must open a PR against GitHub. Not every professor is comfortable with git. A `mailto:` fallback in `NOTES.md` would be a low-cost improvement. 2. **No license file.** Most awesome-lists ship with `CC0` or `MIT`. This list does not. Forking commercially or incorporating it into a product without asking is ambiguous legal ground. 3. **Category ordering is approximate.** Within a category, undergrad-first ordering is honored by custom, not by a lint check. Contributors occasionally file courses "at the end" which requires reviewer re-ordering. 4. **Nested category rendering.** The nested SE and ML categories read as "Software Engineering: Concurrency" rather than true nested sections in markdown. GitHub renders them correctly, but contributors unfamiliar with the convention sometimes create a flat H2. Reviewers should normalize. 5. **No structured data output.** A JSON or RSS feed of new additions could help readers who want a notification stream. Not currently offered. 6. **Link health is manual.** No automated link-checker runs; dead links are reported as issues. Wiring a scheduled GitHub Action running `lychee` monthly and opening issues for failures would be a net improvement. 7. **Category TOC is hand-maintained.** A small script could auto-generate the categories-only index at the top from `##` and `###` headings. Currently the TOC drifts when new categories are added. > [!NOTE] > Items 6 and 7 are the highest-ROI improvements for a new maintainer taking over the project. Both are low-risk (additive changes only) and immediately visible to contributors. --- ## 10. Quick Reference ### File responsibilities | File | Purpose | When to edit | |---|---|---| | `README.md` | The catalog | Every addition, removal, re-categorization, URL fix | | `NOTES.md` | Policy notes for readers and contributors | Policy changes only | | `CONTRIBUTING.md` | PR contract | Contribution-rule changes only | ### Decision flowchart for incoming PRs ```text PR received ├─ Empty issue / no content? → Block and close (spam) ├─ Link is shortened (bit.ly, t.co)? → Request expansion; reject if not fixed ├─ Videos behind registration/paywall? → Reject ├─ Entry is a 4–5 hour MOOC or bootcamp? → Reject with explanation ├─ Format does not match pattern? → Request changes ├─ Correct category and level ordering? → Verify and adjust if needed └─ All checks pass → Merge ``` ### Editor setup recommendations For maintainers reviewing PRs locally: - Use a terminal editor (Vim, Neovim, nano) or VS Code with a whitespace-visibility extension when spot-checking PRs for invisible Unicode — GitHub's rendered view hides these characters. - VS Code users: enable **Render Whitespace** (`"editor.renderWhitespace": "all"`) and the **Unicode Highlight** extension. - A simple `git diff` review in the terminal exposes malformed entries more reliably than the GitHub web UI diff for large README batches. --- _Generated May 2026 from Developer-Y/cs-video-courses at fcd263d. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._