docs: add Windows build instructions, WSL recommendation, Node version requirements, and troubleshooting #3421
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
This PR improves the README by adding clear, detailed documentation for Windows users who experience build failures when running
npm installorpython build.py.Building scratch-blocks currently fails on native Windows due to long command-line limits, deprecated Closure Compiler tooling, Python 2 syntax, and modern Node.js incompatibilities. These issues are well-documented but not yet mentioned in the README.
What This PR Adds
build.pyuses Python 2 syntax)Why This Is Needed
Many contributors on Windows encounter errors like:
These issues are still present and reproducible.
Adding this documentation helps developers avoid failed builds and guides them toward the officially recommended WSL workflow.
Related Issues
Windows: Some build steps fail with "The command line is too long" #2080
Notes
This PR does not modify any existing information — it only appends new documentation sections that help Windows users build the project successfully.