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.

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

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)

Entry format (NOTES.md)

- [<Course-Number> <Course-Name> <Year> <Prof Name> <University/Platform>](<url>) ([Video Playlist](<url>))

• 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:

   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:

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):

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):

grep -oE 'https?://(bit\.ly|t\.co|tinyurl\.com|lnkd\.in|goo\.gl)/[^ )\]]+' README.md

Find invisible Unicode (security hygiene):

grep -nP '[\x{00AD}\x{200B}-\x{200D}\x{202A}-\x{202E}\x{FEFF}]' README.md

Find malformed entries (missing URL, unclosed bracket, etc.):

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:

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):

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

Decision flowchart for incoming PRs

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.