microsoft / microsoft/Web-Dev-For-Beginners
Sparse checkout instructions exclude lesson assets needed for hands-on projects[Docs + DX]
Nobody has claimed this yet.
- 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
-
Audit lesson dependencies: Move all required assets for the default English track out of
translations/andtranslated_images/into each lesson folder. -
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
/assetsfolder at root with all required images. -
Add warning: Note in README that sparse checkout will break specific lessons unless assets are included.
-
CI check: Add GitHub Action to fail if any
_.mdin 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
.mdin the English path referencestranslations/ortranslated_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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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