docs(contributing): add Development Environment section with WSL2 setup guide#59126
docs(contributing): add Development Environment section with WSL2 setup guide#59126alkor2000 wants to merge 3 commits intoopenclaw:mainfrom
Conversation
…up guide Add a new 'Development Environment' section to CONTRIBUTING.md covering: - Prerequisites: Node.js >= 22.12.0 and pnpm requirements - Windows (WSL2): step-by-step notes for WSL2 contributors including systemd enablement, .wslconfig resource limits, terminal behavior, and file system performance guidance - Getting started from source: clone/install/build quick-start commands This information was previously undocumented, leaving Windows contributors to discover WSL2 requirements through trial and error. The WSL2 notes are based on hands-on experience setting up an OpenClaw development environment on a Windows 11 ThinkPad with WSL2 Ubuntu 24.04. AI Disclosure: This PR was developed with AI assistance (Claude). The author has reviewed all content and confirms accuracy from direct experience.
Greptile SummaryThis PR adds a new "Development Environment" section to
Confidence Score: 4/5Safe to merge after fixing the wsl.conf syntax — the current phrasing will silently prevent systemd from being enabled for Windows contributors following the guide. One P1 finding: the /etc/wsl.conf instruction is formatted ambiguously and a user copying it literally will not get systemd enabled, which defeats the primary purpose of that step. The two P2 findings are quality improvements but do not break anything. Score is 4 rather than 5 because of the P1 docs-accuracy bug. CONTRIBUTING.md — specifically the wsl.conf systemd instruction on line 103 and the Node.js version wording on line 90. Prompt To Fix All With AIThis is a comment left during a code review.
Path: CONTRIBUTING.md
Line: 103
Comment:
**`/etc/wsl.conf` INI syntax is ambiguous**
The instruction `add [boot] systemd=true to /etc/wsl.conf` presents a single inline string, but `/etc/wsl.conf` uses standard INI format where `[boot]` must be a standalone section header on its own line, followed by `systemd=true` on the next line. A user who literally adds `[boot] systemd=true` as one line will get no effect — systemd will remain disabled and the error will be silent.
A small code block avoids any ambiguity:
```suggestion
1. **Enable systemd** — add the following to `/etc/wsl.conf` inside your Ubuntu instance and restart WSL (`wsl --shutdown` from PowerShell). The gateway daemon service requires systemd.
```ini
[boot]
systemd=true
```
```
How can I resolve this? If you propose a fix, please make it concise.
---
This is a comment left during a code review.
Path: CONTRIBUTING.md
Line: 95
Comment:
**`sudo npm install -g pnpm` can break nvm-managed installs**
Using `sudo` with npm is the correct approach when Node.js is installed system-wide (e.g. via NodeSource), but it will fail or install to the wrong location when Node.js is managed by `nvm` — which is a very common WSL2 setup. With `nvm`, the prefix is per-user and `sudo` switches to the root user's separate npm environment.
Consider noting the nvm alternative, or dropping `sudo` and letting the reader use whichever approach matches their install:
```suggestion
- **pnpm** — install globally with `npm install -g pnpm` (add `sudo` if Node.js was installed system-wide via NodeSource; omit it if you use nvm). The project workspace configuration requires pnpm; npm alone is not sufficient for source builds.
```
How can I resolve this? If you propose a fix, please make it concise.
---
This is a comment left during a code review.
Path: CONTRIBUTING.md
Line: 90
Comment:
**Node version statement is inconsistent with prerequisites**
The opening sentence says OpenClaw is built on "Node.js 24 LTS", but the Prerequisites bullet immediately below says "Node.js ≥ 22.12.0", and the repository's own `AGENTS.md` defines the runtime baseline as Node 22+. Stating "24 LTS" as the build target while requiring only 22+ is slightly contradictory and may confuse contributors who are on 22.x.
Consider aligning the wording:
```suggestion
OpenClaw is built with **TypeScript** on **Node.js** (22 LTS minimum, 24 LTS recommended) and uses **pnpm** as its package manager for source development.
```
How can I resolve this? If you propose a fix, please make it concise.Reviews (1): Last reviewed commit: "docs(contributing): add Development Envi..." | Re-trigger Greptile |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 25ae201722
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
- P1: wsl.conf systemd instruction now uses a code block instead of ambiguous inline text to prevent silent INI syntax errors (Greptile) - P2: Node.js version wording aligned with repo baseline (22 LTS min, 24 LTS recommended) and minimum bumped to 22.14.0 per package.json engines field (Greptile + Codex) - P2: pnpm install note now covers both system-wide (sudo) and nvm-managed (no sudo) Node.js setups (Greptile)
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 79425ecad6
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
The ini code block for wsl.conf was opened with four backticks but closed with three, causing GitHub Markdown to render the rest of the document as a code block. Also removed an orphan trailing fence at EOF. (Codex P2 review)
|
Codex review: found issues before merge. What this changes: This PR adds a CONTRIBUTING.md Development Environment section covering Node/pnpm prerequisites, WSL2 setup tips, and source-build commands. Maintainer follow-up before merge: This remains a docs/editorial PR that needs maintainer re-scope rather than an autonomous replacement or fix PR. Security review: Security review cleared: Docs-only CONTRIBUTING.md changes do not alter code execution, CI, dependencies, package resolution, secrets handling, or release paths. Review findings:
Review detailsBest possible solution: Keep the contribution open, rebase it, and make CONTRIBUTING.md a short pointer to the canonical setup pages while moving any accepted missing WSL2 contributor tips into docs/platforms/windows.md or docs/start/setup.md. Do we have a high-confidence way to reproduce the issue? Not applicable as a docs PR. The high-confidence review path is comparing the PR diff against current CONTRIBUTING.md, README.md, docs/platforms/windows.md, docs/start/setup.md, and targeted searches for the WSL2 tuning notes. Is this the best way to solve the issue? No. The current PR is useful but no longer the best shape because it duplicates canonical docs and should be re-scoped to links plus narrowly missing WSL2 notes. Full review comments:
Overall correctness: patch is incorrect Acceptance criteria:
What I checked:
Likely related people:
Remaining risk / open question:
Codex review notes: model gpt-5.5, reasoning high; reviewed against 388019f5b693. |
|
Closing — appreciate the triage feedback. Happy to revisit if maintainers want to re-scope the development environment guidance. |
Summary
Add a "Development Environment" section to CONTRIBUTING.md, covering prerequisites, Windows/WSL2 setup, and a quick-start guide for building from source.
Problem
CONTRIBUTING.md currently jumps straight to "Before You PR" without explaining how to set up a development environment. Windows contributors in particular have no guidance on WSL2 — they must discover through trial and error that systemd needs to be enabled, .wslconfig should set resource limits, and the Linux file system should be used for performance.
Changes
New section added between "How to Contribute" and "Before You PR":
/etc/wsl.conf.wslconfigresource limitsContext
These notes are based on setting up an OpenClaw development environment from scratch on a Windows 11 ThinkPad 16 (WSL2 + Ubuntu 24.04 + Node.js 24.14.0 + pnpm 10.32.1). Every tip addresses an actual friction point encountered during the process.
AI Disclosure
This PR was developed with AI assistance (Claude). The author has reviewed all content and confirms accuracy from direct experience.