From cd9e141001101919384d8eb16b90c33e8c20eced Mon Sep 17 00:00:00 2001 From: Hemanth Dhanasekaran <63975676+hemanth1999k@users.noreply.github.com> Date: Wed, 13 May 2026 21:17:17 -0500 Subject: [PATCH] docs: add CONTRIBUTING-BEGINNERS.md for new contributors (#1682) --- CONTRIBUTING-BEGINNERS.md | 297 ++++++++++++++++++++++++++++++++++++++ CONTRIBUTING.md | 2 + 2 files changed, 299 insertions(+) create mode 100644 CONTRIBUTING-BEGINNERS.md diff --git a/CONTRIBUTING-BEGINNERS.md b/CONTRIBUTING-BEGINNERS.md new file mode 100644 index 000000000..561fce785 --- /dev/null +++ b/CONTRIBUTING-BEGINNERS.md @@ -0,0 +1,297 @@ +# Beginner's Guide to Contributing to OpenHuman + +New to open source or coding? This guide walks you through everything from zero to your first pull request — based on real setup pain points that new contributors hit. + +For the full contributor reference, see [`CONTRIBUTING.md`](CONTRIBUTING.md). + +--- + +## Table of Contents + +- [What is this project?](#what-is-this-project) +- [Step 1 — Install the required tools](#step-1--install-the-required-tools) +- [Step 2 — Fork and clone the repo](#step-2--fork-and-clone-the-repo) +- [Step 3 — Finish the local setup](#step-3--finish-the-local-setup) +- [Step 4 — Find an issue to work on](#step-4--find-an-issue-to-work-on) +- [Step 5 — Create your branch](#step-5--create-your-branch) +- [Step 6 — Make your change and verify it](#step-6--make-your-change-and-verify-it) +- [Step 7 — Push and open a Pull Request](#step-7--push-and-open-a-pull-request) +- [Keeping your fork up to date](#keeping-your-fork-up-to-date) +- [Troubleshooting common issues](#troubleshooting-common-issues) + +--- + +## What is this project? + +OpenHuman is a desktop AI assistant app. The codebase has three main parts: + +| Part | Tech | What it does | +|------|------|-------------| +| `app/` | React + TypeScript | The UI — what you see and click | +| `app/src-tauri/` | Rust + Tauri | Wraps the UI into a desktop app | +| `src/` | Rust | The backend brain — logic, memory, RPC | + +**As a beginner**, focus on `app/src/` (React/TypeScript). You don't need to touch Rust to make meaningful contributions. + +--- + +## Step 1 — Install the required tools + +### macOS (recommended for beginners) + +Install [Homebrew](https://brew.sh) first if you don't have it: + +```bash +/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" +``` + +Then install everything the project needs: + +```bash +# Node.js 24+ and pnpm (JavaScript package manager) +brew install node@24 +npm install -g pnpm@10.10.0 + +# Rust (the backend language) +brew install rustup-init +rustup toolchain install 1.93.0 --profile minimal +rustup component add rustfmt clippy --toolchain 1.93.0 + +# CMake (required by Rust dependencies) +brew install cmake + +# Xcode Command Line Tools (macOS build tools) +xcode-select --install +``` + +### Verify everything is installed + +```bash +node --version # should be v24.x.x or higher +pnpm --version # should be 10.10.0 +rustc --version # should be 1.93.0 +cmake --version # any recent version +``` + +> **Node version warning**: The project requires Node 24+. If you see a warning like `Unsupported engine: wanted >=24.0.0 (current: v22.x.x)`, upgrade Node. Using `nvm`? Run `nvm install 24 && nvm use 24`. + +--- + +## Step 2 — Fork and clone the repo + +### 2a. Fork on GitHub + +1. Go to [github.com/tinyhumansai/openhuman](https://github.com/tinyhumansai/openhuman) +2. Click **Fork** (top right) +3. This creates your own copy at `github.com/YOUR_USERNAME/openhuman` + +### 2b. Clone your fork locally + +```bash +git clone https://github.com/YOUR_USERNAME/openhuman.git +cd openhuman +``` + +### 2c. Add the upstream remote + +This links your local copy to the original repo so you can pull in updates later: + +```bash +git remote add upstream https://github.com/tinyhumansai/openhuman.git +``` + +Verify both remotes exist: + +```bash +git remote -v +# origin https://github.com/YOUR_USERNAME/openhuman.git ← your fork +# upstream https://github.com/tinyhumansai/openhuman.git ← the original +``` + +--- + +## Step 3 — Finish the local setup + +### 3a. Initialize submodules + +The project includes vendored Tauri and CEF code as git submodules. You must do this before installing dependencies or desktop builds will fail: + +```bash +git submodule update --init --recursive +``` + +### 3b. Install dependencies + +```bash +pnpm install +``` + +> **pnpm not found?** If your shell can't find `pnpm` after installing it, run `export PATH="$PATH:$(npm root -g)/.bin"` and try again. Add that line to your `~/.zshrc` or `~/.bashrc` to make it permanent. + +### 3c. Set up environment files + +```bash +cp .env.example .env +cp app/.env.example app/.env.local +``` + +The defaults work for web-only development. You don't need to change anything to get started. + +### 3d. Start the app + +```bash +# Web UI only (easiest — runs in your browser) +pnpm dev + +# Full desktop app (needs Rust + Tauri built first) +pnpm --filter openhuman-app dev:app +``` + +For your first contribution, `pnpm dev` is all you need. + +--- + +## Step 4 — Find an issue to work on + +1. Go to [github.com/tinyhumansai/openhuman/issues](https://github.com/tinyhumansai/openhuman/issues) +2. Filter by label — look for `good first issue`, `documentation`, or frontend-related labels +3. Read the issue fully before starting +4. Leave a comment saying you'd like to work on it — this avoids two people solving the same issue + +### Recommended first areas for beginners + +| Area | Where it lives | Skills needed | +|------|---------------|---------------| +| UI components | `app/src/` | React, TypeScript | +| Styles / design | `app/src/`, `app/tailwind.config.js` | CSS, Tailwind | +| Documentation | `*.md` files, `gitbooks/` | Writing | +| Bug fixes (frontend) | `app/src/` | React, TypeScript | + +**Avoid for now**: anything in `src/` (Rust core) or `app/src-tauri/` (Tauri shell) until you're comfortable with the codebase. + +--- + +## Step 5 — Create your branch + +Always create a new branch for each issue. Never work directly on `main`. + +```bash +# Make sure your main is up to date first +git fetch upstream +git checkout main +git pull --ff-only upstream main + +# Create a branch named after what you're doing +git checkout -b fix/your-issue-description +# or +git checkout -b docs/your-doc-change +# or +git checkout -b feat/your-feature-name +``` + +--- + +## Step 6 — Make your change and verify it + +After making your changes, run the relevant checks: + +```bash +# For any change — check formatting +pnpm format:check + +# For frontend code changes +pnpm typecheck # TypeScript errors +pnpm lint # Code style issues + +# Auto-fix formatting issues +pnpm format +``` + +If you only changed documentation (`.md` files), `pnpm format:check` is the only check you need to run. + +--- + +## Step 7 — Push and open a Pull Request + +### Push your branch + +```bash +git add . +git commit -m "your short description of what you changed" +git push -u origin your-branch-name +``` + +### Open the PR + +1. Go to your fork on GitHub: `github.com/YOUR_USERNAME/openhuman` +2. You'll see a **"Compare & pull request"** banner — click it +3. Make sure the PR targets **`tinyhumansai/openhuman:main`** (not your fork) +4. Fill in the PR template completely +5. Link the issue with `Closes #ISSUE_NUMBER` in the description +6. Submit + +--- + +## Keeping your fork up to date + +Before starting any new work, sync your fork with the latest upstream changes: + +```bash +git fetch upstream +git checkout main +git pull --ff-only upstream main +git push origin main +``` + +--- + +## Troubleshooting common issues + +### `pnpm: command not found` + +pnpm was installed but your shell can't find it. Fix: + +```bash +export PATH="$PATH:$(npm root -g)/.bin" +``` + +Make it permanent by adding that line to `~/.zshrc`. + +### `submodule` errors or missing Tauri vendor files + +You skipped the submodule step. Run: + +```bash +git submodule update --init --recursive +``` + +### Node version warning during `pnpm install` + +The project requires Node 24+. Upgrade: + +```bash +# If using nvm +nvm install 24 +nvm use 24 + +# If using Homebrew +brew install node@24 +``` + +### `pnpm typecheck` or `pnpm lint` errors on unchanged files + +These may be pre-existing issues on `main` unrelated to your change. Note them in your PR description and proceed. + +### Desktop build fails (`pnpm --filter openhuman-app dev:app`) + +The desktop build requires the full Rust toolchain and vendored Tauri setup. For your first contributions, stick to `pnpm dev` (web mode) and skip the desktop build entirely. + +--- + +## Still stuck? + +- Join the [Discord](https://discord.tinyhumans.ai/) and ask in the contributors channel +- Comment on the issue you're working on +- Check [`gitbooks/developing/getting-set-up.md`](gitbooks/developing/getting-set-up.md) for deeper setup docs + +Thank you for contributing to OpenHuman! diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3b7a7dfdd..e9508230e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,6 +2,8 @@ Thank you for your interest in contributing to OpenHuman. This guide is the fast path for getting a fresh checkout running locally, validating changes, and opening a pull request without having to piece together setup notes from multiple files. +> **New to open source or coding?** Start with [`CONTRIBUTING-BEGINNERS.md`](CONTRIBUTING-BEGINNERS.md) — it walks you through every step from installing tools to opening your first PR. + For deeper architecture and subsystem references, use the GitBook under [`gitbooks/developing/`](gitbooks/developing/). For coding-agent and repository-specific implementation rules, see [`AGENTS.md`](AGENTS.md) and [`CLAUDE.md`](CLAUDE.md). ## Table of Contents