Skip to content

CONTRIBUTING.md

Latest commit

ย 

History

History
196 lines (137 loc) ยท 8.2 KB

CONTRIBUTING.md

File metadata and controls

196 lines (137 loc) ยท 8.2 KB
Raw

Contributing to nexu

This file is the canonical English contributing guide. The docs site embeds it on docs.nexu.io โ€” Contributing. ็ฎ€ไฝ“ไธญๆ–‡ไธบ็‹ฌ็ซ‹่ฏ‘ๆœฌ๏ผšไป“ๅบ“ๅ†… docs/zh/guide/contributing.md๏ผˆ็บฟไธŠ๏ผ‰ใ€‚

Thank you for helping improve nexu. The sections below cover code, documentation, and how we review changes.

If you want a lower-friction entry point, we are actively looking for Good First Issue contributors. Start with the good-first-issue label or the Chinese first-PR guide.

Community standards

Ways to contribute

  • Bug reports โ€” reproducible steps, version/OS, logs (redact secrets).
  • Feature ideas โ€” open a Discussion or Issue so maintainers can align before large PRs.
  • Code โ€” fixes and features that match the project scope.
  • Docs โ€” fixes, translations, screenshots, and clarity improvements (English + Chinese when both exist).

Before you write code

  1. Search Issues and Discussions for duplicates.
  2. For non-trivial changes, open an Issue first (or comment on an existing one) to agree on direction.
  3. Fork the repo and work on a short-lived branch off main.

Development setup

Prerequisites

  • Git
  • Node.js 24+ (LTS recommended; enforced via package.json engines)
  • pnpm 10.26+ (repo pins pnpm@10.26.0 via packageManager)
  • npm 11+ (required for repo-local OpenClaw runtime maintenance flows)

Clone and install

From the repository root (not only docs/):

git clone https://github.com/nexu-io/nexu.git
cd nexu
pnpm install

postinstall runs scripts (including OpenClaw runtime setup). The first install can take a while.

Repository layout (excerpt)

nexu/
โ”œโ”€โ”€ apps/
โ”‚   โ”œโ”€โ”€ web/              # React + Ant Design dashboard
โ”‚   โ”œโ”€โ”€ desktop/          # Electron desktop shell
โ”‚   โ””โ”€โ”€ controller/       # Hono backend + OpenClaw orchestration
โ”œโ”€โ”€ packages/shared/      # Shared Zod schemas
โ”œโ”€โ”€ packages/slimclaw/    # Repo-local OpenClaw runtime contract + prepared runtime ownership
โ”œโ”€โ”€ scripts/              # Dev/CI scripts (launchd, probes, e2e)
โ”œโ”€โ”€ tests/                # Vitest test suites
โ”œโ”€โ”€ docs/                 # VitePress documentation site
โ””โ”€โ”€ specs/                # Design docs, product specs

Common commands

Run from the repo root unless noted.

Command Purpose
pnpm dev Dev stack (controller + web) with hot reload
pnpm start Full desktop runtime (Electron + launchd services, macOS only)
pnpm stop Stop desktop runtime (graceful SIGTERM โ†’ SIGKILL fallback)
pnpm status Show desktop runtime status
pnpm dev:controller Controller only
pnpm build Production build (all packages)
pnpm typecheck TypeScript checks across the workspace
pnpm lint Biome check only
pnpm lint:fix Auto-fix where safe with Biome only
pnpm format Format/write with Biome
pnpm test Root Vitest suite (vitest run)
pnpm check:esm-imports ESM specifier verification (also run in CI)
pnpm dist:mac:unsigned Build unsigned macOS desktop app for local testing

Some packages define their own scripts (for example pnpm --filter @nexu/web test:e2e for Playwright). Prefer the closest package.json to the code you change.

Note for desktop contributors: pnpm start requires macOS (uses launchd for process management). The test suite includes real launchd integration tests that only run on macOS โ€” they're automatically skipped on other platforms. If you're contributing to desktop code, test on macOS before submitting a PR.

Code style and formatting

  • Biome is the source of truth for formatting and many lint rules (biome.json).
  • Pre-commit: pnpm prepare installs scripts/pre-commit into .git/hooks when possible; it runs Biome on staged *.ts, *.tsx, *.js, *.jsx, *.json files.
  • Alternative hook path: git config core.hooksPath scripts (then use hooks under scripts/ as documented in scripts/pre-commit).

Run before pushing:

pnpm lint
pnpm typecheck
pnpm test

If you touched production build paths:

pnpm build
pnpm check:esm-imports

Commits

We recommend Conventional Commits-style messages so history and changelogs stay readable:

  • feat: โ€ฆ โ€” new feature
  • fix: โ€ฆ โ€” bug fix
  • docs: โ€ฆ โ€” documentation only
  • chore: โ€ฆ โ€” tooling, deps, no user-facing change
  • refactor: โ€ฆ โ€” behavior-preserving code change

Use the imperative mood (add, fix, not added / fixed). Split unrelated changes into separate commits when practical.

Pull requests

  1. Branch from main: e.g. fix/login-validation or feat/feishu-webhook.
  2. Scope โ€” one logical change per PR; avoid drive-by reformats across the repo.
  3. Title โ€” clear, concise; match Conventional Commits if you can.
  4. Description โ€” what/why, how to test, screenshots or screen recordings for UI changes.
  5. Link issues โ€” use Fixes #123 or Closes #123 when applicable.
  6. Secrets โ€” never commit tokens, API keys, or personal credentials. Use env vars and local-only config.

Maintainers may squash or adjust commit messages on merge; keeping your branch rebased on main reduces friction.

CI expectations

  • Code PRs โ€” .github/workflows/ci.yml runs typecheck, pnpm lint, pnpm build, and pnpm check:esm-imports. Pushes that only change files under docs/ skip this workflow (paths-ignore).
  • Docs PRs โ€” .github/workflows/docs-ci.yml builds the docs site when docs/ or CONTRIBUTING.md changes.

Green CI is required before merge unless a maintainer says otherwise.

Documentation contributions

Run the docs site locally

cd docs
pnpm install   # first time only
pnpm dev

VitePress prints a local URL; use it to verify headings, links, and images.

Writing workflow

  • English narrative in this guide is maintained in CONTRIBUTING.md at the repo root and included into the English docs page; edit that file for English prose, unless you are only fixing VitePress-only wiring.
  • English pages under docs/en/: other guides stay in docs/en/.
  • Chinese pages: docs/zh/
  • New sidebar entries: update docs/.vitepress/config.ts
  • When you add or substantially change a guide, keep English and Chinese in sync when both locales exist.

Paste images into Markdown

We recommend the telesoho.vscode-markdown-paste-image extension.

Workspace default (see .vscode/settings.json):

{
  "MarkdownPaste.path": "${workspaceFolder}/docs/public/assets"
}
  1. Copy a screenshot to the clipboard.
  2. Open the target file under docs/en/ or docs/zh/.
  3. Run Markdown Paste or Cmd+Option+V (macOS) / Ctrl+Alt+V (Windows/Linux).

Link images from the site root:

![Describe the screenshot](/assets/example-image.png)

Use descriptive filenames and alt text.

Before you submit doc changes

  • Both en and zh updated if the page exists in both languages
  • pnpm dev preview looks correct
  • New assets load from /assets/...
  • Sidebar updated when adding a new page

Reviews

Reviewers care about correctness, security/privacy, maintainability, and user-facing clarity. Smaller PRs are reviewed faster.

Again: thank you for contributing โ€” questions are welcome in Discussions.