docs: Rewrite setup as devcontainer steps per platform - #8062
Conversation
Setup was three parallel routes, one of which told mac users to edit a homebrew formula to get around a disabled lua@5.1. Replaces all of it with numbered steps for docker, vs code, clone, open, verify, with the platform differences stated only where they differ: docker engine rather than docker desktop on linux, wsl 2 on windows, and cloning inside wsl rather than on the windows drive. Drops the native toolchain instructions and the per editor lsp setup, since the container supplies both and the extensions install themselves. Two things elsewhere were wrong and would bite the same reader: `npm run test` and `npm run fix` do not exist, and the deploy section still asked for a pip install and an .env copy that the container does on first start.
There was a problem hiding this comment.
🟡 Changes recommended
The Linux Docker install command in the README pipes the installer to sh without elevated privileges, which is likely to fail for most readers unless corrected (e.g., sudo sh).
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
This PR rewrites the contributor setup documentation to make the devcontainer the primary/only supported onboarding path, consolidating platform-specific notes into a single numbered flow and removing the prior native setup + per-editor LSP instructions.
Changes:
- Replaced the previous “Devcontainer + native Linux/macOS/Windows” setup sections with a single devcontainer-first, step-by-step workflow (Docker → VS Code → clone → reopen in container → verify).
- Updated commands/docs to match current tooling (e.g.,
npm run test:jsandnpm run lintrather than non-existentnpm run test/npm run fix). - Updated “From your machine” deploy setup notes to reflect devcontainer post-create behavior (Python deps installed and
.envcreated withDRY_RUN=1).
File summaries
| File | Description |
|---|---|
| README.md | Reworks setup and local-dev docs around the devcontainer workflow; updates test/lint script names and deploy prerequisites to match current repo behavior. |
Review details
- Files reviewed: 1/1 changed files
- Comments generated: 1
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Install steps for other people's tools go stale here and are documented better at the source. Keeps only what is our decision: docker engine rather than desktop on linux, and the WSL 2 backend on windows. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
ElectricalBoy
left a comment
ElectricalBoy
left a comment
There was a problem hiding this comment.
I would prefer not removing the old instructions entirely - I don't see a problem with making devcontainer the suggested setup but I think it is better to keep instructions for native setup for people who prefer not installing docker.
What
Setup had three parallel routes — devcontainer, native Unix, native Mac — plus per-editor LSP config. The Mac route told people to edit a Homebrew formula to install a disabled
lua@5.1. Now all merged, the devcontainer is the one path, so this replaces the lot with numbered steps: install Docker, install VS Code, clone, open in container, verify.Platform differences appear only where they actually differ:
dockergroup stepRemove a bunch of stuff that was either incorrect or confusing.