The Problem

Maintaining a large, community‑curated list of tutorial URLs quickly devolves into “link rot”. Contributors need a reliable way to detect broken links before they are merged, and repository owners need minimal manual effort to keep the list healthy.

What This Does

The repository is a markdown‑based catalogue of project‑based tutorials, organized by language in README.md. The only executable component is a small Python utility scripts/check_readme.py that parses the README, extracts HTTP links, and validates their HTTP status. Supporting data files – scripts/linkcheck-domains.txt (whitelisted domains) and scripts/lint‑allow‑duplicates.txt (duplicate‑link policy) – feed the validator.

GitHub Actions defined in .github/workflows/ orchestrate the validation:

  • link‑rot.yml runs the Python script on a nightly schedule and on pull‑request events.
  • validate‑pr.yml enforces that any PR altering the README also passes the link check.
  • stale‑prs.yml automatically closes inactive PRs.

Issue‑ and PR‑templates guide contributors to report broken links or suggest new tutorials, keeping the contribution workflow consistent.

How It Is Wired

Entry point

  • GitHub Action link‑rot.yml → uses: actions/setup-python@v4 → python scripts/check_readme.py.
  • Locally, the same entry point is the command python scripts/check_readme.py.

Call graph (internal)

  1. check_readme.py reads README.md → extract_links() (regex over markdown).
  2. For each URL, validate_link(url) performs an HTTP HEAD request (fallback to GET on 405).
  3. Responses are cross‑checked against linkcheck‑domains.txt (allowed hosts) and lint‑allow‑duplicates.txt (whether repeats are permissible).
  4. Results are aggregated; the script exits with status 0 if all links are alive, non‑zero otherwise, which GitHub Actions interprets as success/failure.

No other modules import or call these functions, so the blast radius is limited to the README file and the two data files. The CI workflows are the only external consumers, invoking the script via the containerized runner environment.

Missing wiring

The repository contains no executable server, database, or CLI beyond the link checker. Consequently, there is no documented internal API or library usage for other tools.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/project-based-learning
cd project-based-learning

# Install runtime (Python 3.9+ recommended)
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt   # (requirements.txt is not present; only stdlib used)

# Run the link validator locally
python scripts/check_readme.py

If the command exits with code 0, all links are reachable. A non‑zero exit prints a list of URLs with HTTP status codes or connection errors. To integrate locally, add the script as a pre‑commit hook or run it as part of a CI pipeline.

Real‑World Use

A tech‑education platform could fork this repo, add its own curated tutorials, and schedule the existing GitHub Action to keep its public resource page free of dead links. The platform would only need to maintain the README structure; the link‑check workflow automatically flags problems before deployment.

Code Health & Issues

  • Medium – No test suite – repository has no tests/ directory; link‑check logic is exercised only by CI runs.
  • Low – Limited documentation – only the README and CONTRIBUTING.md describe contribution flow; the Python script lacks inline docstrings.
  • Low – Single‑point failure – the entire health check depends on check_readme.py; any bug there blocks all CI validations.
  • Info – CI present – GitHub Actions provide automated validation, reducing manual effort.

No secrets, Dockerfiles, or compiled binaries are present.

The Bottom Line

The repo delivers a focused, automated solution for detecting broken tutorial links in a markdown catalogue, leveraging a lightweight Python script and GitHub Actions. It lacks tests and deeper documentation, so contributors should be comfortable editing the script if needed. Ideal for teams that need a low‑maintenance, link‑health guard for static resource lists.