docs: clarify contributor setup#1618
Conversation
📝 WalkthroughWalkthroughDocumentation updates consolidate contributor onboarding: README adds a "Contributing from source" checklist; CONTRIBUTING and gitbooks pin tool versions, add CMake and a macOS Homebrew bootstrap, and make build-from-source steps explicit; internal docs links are retargeted to architecture-focused GitBook pages and Tailwind token locations. ChangesContributor Documentation Updates
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Tip 💬 Introducing Slack Agent: The best way for teams to turn conversations into code.Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.
Built for teams:
One agent for your entire SDLC. Right inside Slack. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@gitbooks/developing/getting-set-up.md`:
- Around line 64-68: Add a brief clarification after the existing "cd app" step
that states which commands are run from the app/ directory vs the workspace
root: indicate that "pnpm dev" is run inside the app/ folder (after cd app) and
that "pnpm --filter openhuman-app dev:app" must be executed from the
repository/workspace root (so change back to the repo root before running it).
Reference the existing tokens "cd app", "pnpm dev", and "pnpm --filter
openhuman-app dev:app" so readers know exactly where to run each command.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 344eb04d-bba6-4f86-8b17-d38f8eac685f
📒 Files selected for processing (6)
AGENTS.mdCLAUDE.mdCONTRIBUTING.mdREADME.mdgitbooks/developing/README.mdgitbooks/developing/getting-set-up.md
honor2030
force-pushed
the
docs/contributor-setup-env
branch
from
ce551fc to
6ed8cef
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
gitbooks/developing/getting-set-up.md (1)
53-55: ⚡ Quick winConsider removing or better justifying the no-op build step.
Step 5 explicitly states that
pnpm core:stageis "currently a no-op; kept for script compatibility." Documenting a step that does nothing creates unnecessary friction in contributor onboarding and may confuse first-time builders.If this command is truly vestigial and has no side effects, consider removing it from the documented workflow. If it must remain for compatibility with automation scripts, add a note explaining which scripts depend on it or when it will be needed again.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@gitbooks/developing/getting-set-up.md` around lines 53 - 55, Step 5 documents a no-op command "pnpm core:stage" which confuses contributors; either remove the two lines that run "cd app" and "pnpm core:stage" from the setup steps or replace them with a short justification paragraph explaining why "pnpm core:stage" must remain (e.g., which automation scripts or CI jobs expect that target, or planned future use), referencing the exact command "pnpm core:stage" and the Step 5 heading so reviewers can locate and validate the change.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@gitbooks/developing/getting-set-up.md`:
- Around line 27-33: Replace installing pnpm via Homebrew with enabling Node's
Corepack so the repo's pinned pnpm@10.10.0 from package.json is used: change the
install line to remove `pnpm` (use `brew install node@24 rustup-init cmake`) and
add a step to run `corepack enable` after Node is installed; mention
`pnpm@10.10.0` and the `packageManager` field so contributors know Corepack will
provide the correct pnpm version automatically.
---
Nitpick comments:
In `@gitbooks/developing/getting-set-up.md`:
- Around line 53-55: Step 5 documents a no-op command "pnpm core:stage" which
confuses contributors; either remove the two lines that run "cd app" and "pnpm
core:stage" from the setup steps or replace them with a short justification
paragraph explaining why "pnpm core:stage" must remain (e.g., which automation
scripts or CI jobs expect that target, or planned future use), referencing the
exact command "pnpm core:stage" and the Step 5 heading so reviewers can locate
and validate the change.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 81b49a7d-7006-4c02-bbc7-5bd4d9983146
📒 Files selected for processing (6)
AGENTS.mdCLAUDE.mdCONTRIBUTING.mdREADME.mdgitbooks/developing/README.mdgitbooks/developing/getting-set-up.md
✅ Files skipped from review due to trivial changes (5)
- README.md
- gitbooks/developing/README.md
- CONTRIBUTING.md
- AGENTS.md
- CLAUDE.md
| macOS Homebrew quick start: | ||
|
|
||
| ```bash | ||
| brew install node@24 pnpm rustup-init cmake | ||
| rustup toolchain install 1.93.0 --profile minimal | ||
| rustup component add rustfmt clippy --toolchain 1.93.0 | ||
| ``` |
There was a problem hiding this comment.
The pnpm installation method may not honor the pinned version.
Line 30 uses brew install pnpm, which typically installs Homebrew's latest stable pnpm package rather than the specific pnpm@10.10.0 version required by line 21. This discrepancy will cause contributors to have the wrong pnpm version, potentially leading to lockfile incompatibility or installation failures.
📦 Proposed fix using Node.js corepack
macOS Homebrew quick start:
```bash
-brew install node@24 pnpm rustup-init cmake
+brew install node@24 rustup-init cmake
+corepack enable
rustup toolchain install 1.93.0 --profile minimal
rustup component add rustfmt clippy --toolchain 1.93.0
After installing Node.js, `corepack enable` allows the `packageManager` field in `package.json` to automatically provide the correct pnpm version when you run `pnpm` commands.
</details>
<!-- suggestion_start -->
<details>
<summary>📝 Committable suggestion</summary>
> ‼️ **IMPORTANT**
> Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
```suggestion
macOS Homebrew quick start:
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@gitbooks/developing/getting-set-up.md` around lines 27 - 33, Replace
installing pnpm via Homebrew with enabling Node's Corepack so the repo's pinned
pnpm@10.10.0 from package.json is used: change the install line to remove `pnpm`
(use `brew install node@24 rustup-init cmake`) and add a step to run `corepack
enable` after Node is installed; mention `pnpm@10.10.0` and the `packageManager`
field so contributors know Corepack will provide the correct pnpm version
automatically.
graycyrus
left a comment
graycyrus
left a comment
There was a problem hiding this comment.
Walkthrough
Docs-only PR that adds a contributor quick-start section to the README, pins tool versions (Node 24+, pnpm 10.10.0, Rust 1.93.0, CMake) in prerequisites, adds a macOS Homebrew bootstrap example, and retargets stale doc links from gitbooks/developing/{frontend,tauri-shell,coding-harness}.md to their current gitbooks/developing/architecture/ paths. Also cleans up a dead Telegram deep-links reference and swaps the design-language.md pointer for app/tailwind.config.js.
Change Summary
| File | Change | Notes |
|---|---|---|
AGENTS.md |
Link retarget (×3) | frontend, tauri-shell → architecture/; design-language → tailwind config; remove dead telegram-login-desktop.md ref |
CLAUDE.md |
Link retarget (×3) | Same pattern: frontend, tauri-shell, coding-harness → architecture/ paths; design → tailwind config |
CONTRIBUTING.md |
Prerequisites + Homebrew bootstrap | CMake row added; macOS brew example; link retarget (frontend, tauri-shell) |
README.md |
New "Contributing from source" section | Quick-start steps, local file link for Cloud Deploy |
gitbooks/developing/README.md |
Fix broken GitBook link | /broken/pages/... → architecture/agent-harness.md |
gitbooks/developing/getting-set-up.md |
Major rewrite | Pinned versions, submodule step, Homebrew bootstrap, working-directory clarifications |
Per-file analysis
Link retargets (AGENTS.md, CLAUDE.md, CONTRIBUTING.md, gitbooks/developing/README.md): All verified — old targets (frontend.md, tauri-shell.md, coding-harness.md, design-language.md) no longer exist on main; new targets under architecture/ all exist. The broken GitBook placeholder link (/broken/pages/...) is correctly replaced with architecture/agent-harness.md. Clean.
README.md: Good quick-start section. The Cloud Deploy link changed from an external gitbook URL to a local file path — works, but the two adjacent links (Architecture, Getting Set Up) still use external gitbook URLs, creating a mix of local and external references on the same line.
getting-set-up.md: Well-structured rewrite. Submodule init step correctly added before pnpm install. Working directory clarifications for pnpm dev vs pnpm --filter openhuman-app dev:app were addressed in a follow-up commit.
Issue coverage gap
Issue #1600 asks for "troubleshooting tips for installation" — this PR doesn't add a troubleshooting section. Not blocking, but worth noting as a follow-up item.
Overall
Solid docs improvement. Link retargets are all correct and verified against the current tree. The prerequisite pinning and Homebrew bootstrap will meaningfully help new contributors. Two minor items flagged inline.
| ## Design | ||
|
|
||
| Premium, calm visual language — ocean primary `#4A83DD`, sage / amber / coral semantics, Inter + Cabinet Grotesk + JetBrains Mono, Tailwind with custom radii/spacing/shadows. See [`gitbooks/resources/design-language.md`](gitbooks/resources/design-language.md). | ||
| Premium, calm visual language — ocean primary `#4A83DD`, sage / amber / coral semantics, Inter + Cabinet Grotesk + JetBrains Mono, Tailwind with custom radii/spacing/shadows. Implementation tokens live in [`app/tailwind.config.js`](app/tailwind.config.js). |
There was a problem hiding this comment.
[minor] The old line pointed to design-language.md which described the full design philosophy (color rationale, typography choices, spacing). The replacement app/tailwind.config.js only contains implementation tokens — a contributor reading CLAUDE.md for design guidance will find Tailwind values but no narrative context.
Since design-language.md no longer exists, this is the best available target. Consider a follow-up to recreate design narrative docs if design decisions need to be communicated to contributors.
| 2. Fork and clone the repo, then run `git submodule update --init --recursive` before `pnpm install` so the vendored Tauri/CEF sources are present. | ||
| 3. Use `pnpm dev` for web-only UI work, `pnpm --filter openhuman-app dev:app` for the desktop shell, and focused checks such as `pnpm typecheck`, `pnpm format:check`, and `cargo check -p openhuman --lib` before opening a PR. | ||
|
|
||
| Deeper docs: [Architecture](https://tinyhumans.gitbook.io/openhuman/developing/architecture) · [Getting Set Up](https://tinyhumans.gitbook.io/openhuman/developing/getting-set-up) · [Cloud Deploy](./gitbooks/features/cloud-deploy.md). |
There was a problem hiding this comment.
[minor] This line now mixes external gitbook URLs (Architecture, Getting Set Up) with a local file path (./gitbooks/features/cloud-deploy.md). Consider making them consistent — either all external or all local.
| Deeper docs: [Architecture](https://tinyhumans.gitbook.io/openhuman/developing/architecture) · [Getting Set Up](https://tinyhumans.gitbook.io/openhuman/developing/getting-set-up) · [Cloud Deploy](./gitbooks/features/cloud-deploy.md). | |
| Deeper docs: [Architecture](gitbooks/developing/architecture.md) · [Getting Set Up](gitbooks/developing/getting-set-up.md) · [Cloud Deploy](gitbooks/features/cloud-deploy.md). |
Co-authored-by: honor2030 <19909783+honor2030@users.noreply.github.com>
3 participants
Summary
Problem
Issue #1600 notes that first-time contributor setup docs are too sparse. The current docs did not call out CMake, submodules, the pinned toolchain versions, or the preferred desktop dev command clearly enough, and several internal contributor links pointed at moved or missing pages.
Solution
README.md,CONTRIBUTING.md, andgitbooks/developing/getting-set-up.md.gitbooks/developing/{frontend,tauri-shell}.mdtogitbooks/developing/architecture/{frontend,tauri-shell}.mdand replaced a broken GitBook placeholder link with the agent harness page.Submission Checklist
diff-cover) meet the gate enforced by.github/workflows/coverage.yml. Runpnpm test:coverageandpnpm test:rustlocally; PRs below 80% on changed lines will not merge. — N/A: documentation-only change with no executable coverage surface.docs/TEST-COVERAGE-MATRIX.mdreflect this change (orN/A: behaviour-only change) — N/A: no feature row changed.## Related— N/A: no affected feature IDs.docs/RELEASE-MANUAL-SMOKE.md) — N/A: contributor docs only, not a release-cut surface.Closes #NNNin the## RelatedsectionImpact
Related
AI Authored PR Metadata (required for Codex/Linear PRs)
Linear Issue
Commit & Branch
Validation Run
pnpm --filter openhuman-app format:checkpnpm typecheckpython3local markdown link checker over README/CONTRIBUTING/AGENTS/CLAUDE andgitbooks/developing/**/*.md(TOTAL_MISSING=0)pnpm --filter openhuman-app format:checkincludescargo fmt --manifest-path ../Cargo.toml --all --check; no Rust code changed.pnpm --filter openhuman-app format:checkincludescargo fmt --manifest-path src-tauri/Cargo.toml --all --check; no Tauri code changed.Validation Blocked
command:N/Aerror:N/Aimpact:N/ABehavior Changes
Parity Contract
Duplicate / Superseded PR Handling
Summary by CodeRabbit