microsoft / microsoft/Web-Dev-For-Beginners

Sparse checkout instructions exclude lesson assets needed for hands-on projects[Docs + DX]

Open
#1,820 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

no-issue-activity
Dominant language
JavaScript
Stars
96.7k
Forks
15.9k
PR merge metrics
No merged PRs in 30d

Description

Description
The README recommends using sparse checkout to avoid downloading 50+ translations:

git sparse-checkout set --no-cone '/*' '!translations' '!translated_images'

Problem: Several lessons reference images and starter files that live inside translations/ even for the English course. Example: 1-getting-started-lessons/3-accessibility/translations/README.md contains the main lesson for some languages, but 1-getting-started-lessons/3-accessibility/assignment.md links to ./images/terrarium.png which only exists in translated_images/espanol/images/.

Result: Students following the sparse checkout steps get broken images and missing starter files for lessons like the terrarium, space game, and browser extension. They think the repo is broken.

Proposed Solution

  1. Audit lesson dependencies: Move all required assets for the default English track out of translations/ and translated_images/ into each lesson folder.

  2. Update sparse checkout command: If some shared assets must stay in translated_images, change the command to:

    git sparse-checkout set --no-cone '/*' '!translations' 'translated_images/english'

    Or keep a /assets folder at root with all required images.

  3. Add warning: Note in README that sparse checkout will break specific lessons unless assets are included.

  4. CI check: Add GitHub Action to fail if any _.md in default lessons links to a path excluded by the recommended sparse checkout.

Acceptance Criteria

  • Cloning with README sparse checkout command lets users complete all 24 lessons without 404s for images/assets
  • No lesson .md in the English path references translations/ or translated_images/
  • README clearly lists which lessons break if users exclude images
  • Test: Run sparse checkout, then find . -name "_.html" -o -name "*.md" | xargs grep "src=" | grep "404" returns nothing

Technical Notes
Affected lessons so far: terrarium project, typing-game, browser-extension. All link to images under translated_images/. The course is “project-based” so broken assets block completion.

Priority:High — breaks onboarding for beginners, which is the core audience
Labels: bug, documentation, good-first-issue, help-wanted

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the README sparse-checkout command, then inspect 1-getting-started-lessons/3-accessibility/assignment.md and the affected terrarium, typing-game, and browser-extension lesson references. Compare those links with translated_images/espanol/images and the excluded paths, then validate the sparse checkout against all 24 lessons. Done means the stated acceptance checks pass and required assets no longer produce broken links.

Written by the indexing model from the issue text.

Assessment

Tech stack
git
Domain
ci-cd, developer-experience, documentation
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.