CONTRIBUTING: Windows contributor setup is incomplete and pins a stale Rust version

[yh928]

Summary

A few gaps make the documented Windows setup fail for a fresh contributor: the pinned Rust version in CONTRIBUTING.md is stale, Ninja isn't listed for Windows, the default dev port collides with a Windows reserved range, and dev:app is macOS-only. Each was hit on a clean Windows 11 checkout while making a first contribution.

Problem

Following CONTRIBUTING.md on Windows 11, in order:

1. Rust version is stale. The prereqs table says Rust | 1.93.0 (CONTRIBUTING.md#L40) and the bootstrap runs rustup toolchain install 1.93.0 (L114–115), but rust-toolchain.toml pins channel = "1.96.1" — and its own comment explains 1.96 is required (rusqlite 0.40 / libsqlite3-sys 0.38 use cfg_select!, stabilized in 1.96). A contributor who installs 1.93 per the docs cannot build.

2. Ninja is not listed for Windows. The prereqs table marks Ninja "Required on macOS to build the bundled CEF helper" (CONTRIBUTING.md#L42), and the Windows-specific setup section (VS Build Tools → LLVM → CMake → Node) never mentions it. But cef-dll-sys needs Ninja on Windows too — without it CMake aborts with CMake was unable to find a build program corresponding to "Ninja".

3. Default dev port 1420 collides with a Windows reserved range. app/src-tauri/tauri.conf.json hardcodes devUrl: http://localhost:1420 and app/vite.config.ts defaults to 1420 (its own comment calls it "the hardcoded 1420 collision"). On Windows with Hyper-V/WSL, 1420 commonly falls inside a system-reserved TCP excludedportrange, so Vite fails with EACCES: permission denied 0.0.0.0:1420. OPENHUMAN_DEV_PORT overrides Vite, but pnpm tauri dev still needs a matching --config devUrl override, and neither is documented.

4. dev:app is macOS-only but documented as the "preferred desktop path." app/package.json's dev:app script uses $HOME/Library/Caches/tauri-cef, scripts/setup-chromium-safe-storage.sh, and APPLE_SIGNING_IDENTITY='OpenHuman Dev Signer' — none of which apply on Windows. CONTRIBUTING.md calls it "the preferred entrypoint … pnpm --filter openhuman-app dev:app" without noting Windows contributors should use pnpm tauri dev instead.

5. Non-UTF-8 system codepage breaks the CEF build. On a non-UTF-8 Windows system codepage (e.g. Korean cp949), the CEF/whisper native compile hits C4819 (character can't be represented in the current codepage) which, under /WX, becomes a hard C2220 error. Setting CL=/utf-8 works around it; it isn't documented.

None of these are blockers for anyone who already has a working environment — they specifically hit new Windows contributors following the docs. Precedent: #1254 (pre-push on Windows) and #1781 (missing macOS prereqs incl. Ninja) fixed the analogous gaps for their platforms.

Solution (optional)

Docs-only for 1, 2, 4, 5; 3 is docs plus a small config decision:

• Update the prereqs table + bootstrap commands to 1.96.1 (single source of truth is rust-toolchain.toml).
• Add Ninja to the Windows-specific setup section.
• Add a note that Windows contributors use pnpm tauri dev (not dev:app).
• Document CL=/utf-8 for non-UTF-8 codepages.
• Document OPENHUMAN_DEV_PORT + the matching pnpm tauri dev --config override for the 1420 clash (or move the default off the reserved range).

Happy to open the docs PR if the direction is agreeable.

Acceptance criteria

• Prereqs table + bootstrap install the toolchain that matches rust-toolchain.toml
• Ninja is listed for Windows
• Windows desktop dev entrypoint (pnpm tauri dev) is documented, with the port-override note
• CL=/utf-8 workaround documented for non-UTF-8 codepages

Related

• Pre-push hook fails on Windows due to missing repo-wide line-ending policy #1254 (pre-push hook fails on Windows), docs(CONTRIBUTING): add missing macOS prereqs (Ninja, x86_64 target, codesign script) #1781 (missing macOS prereqs incl. Ninja) — same class of platform-setup gap.
• Found while preparing feat(mcp): add hand-entered (custom) MCP servers #5033.