From 1f08dd920f63824c086a3116d96bd59a191d5b31 Mon Sep 17 00:00:00 2001 From: JD Date: Mon, 18 May 2026 16:12:45 +0000 Subject: [PATCH 1/5] docs: add CONTRIBUTING.md guide for new contributors Provides a complete onboarding guide covering: - Quick start setup - Finding issues to work on (label guide) - Branch naming conventions - Development workflow (fork, branch, commit, PR) - Project structure overview with key file paths - Styling conventions and file size guidelines - i18n workflow for adding translations - Code principles (KISS, DRY, single responsibility) This gives new contributors everything they need in one place to start contributing effectively. --- CONTRIBUTING.md | 144 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 144 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..5caec4a4a --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,144 @@ +# Contributing to CodeNomad + +Thank you for your interest in contributing! This guide will help you get started. + +## Quick Start + +```bash +git clone https://github.com/NeuralNomadsAI/CodeNomad.git +cd CodeNomad +npm install +npm run dev +``` + +## Finding Issues to Work On + +Browse [open issues](https://github.com/NeuralNomadsAI/CodeNomad/issues) and look for these labels: + +| Label | Meaning | +|---|---| +| `ready-to-work` | Clear scope, ready for anyone to pick up | +| `good-first-issue` | Good for first-time contributors | +| `enhancement` | New feature requests | +| `bug` | Bug reports | + +**Before starting:** comment on the issue so we can discuss approach and avoid duplicate work. + +## Development Workflow + +### 1. Fork and Branch + +```bash +# Fork the repo on GitHub, then clone your fork +git clone https://github.com/YOUR_USERNAME/CodeNomad.git +cd CodeNomad + +# Add the upstream remote +git remote add upstream https://github.com/NeuralNomadsAI/CodeNomad.git + +# Create a branch from upstream/dev +git fetch upstream +git checkout -b fix/your-branch-name upstream/dev +``` + +### 2. Branch Naming + +| Prefix | Use for | +|---|---| +| `fix/` | Bug fixes | +| `feat/` | New features | +| `docs/` | Documentation changes | +| `refactor/` | Code refactoring | +| `chore/` | Build, config, maintenance | + +Examples: `fix/question-queue-ordering`, `feat/retry-tool-call`, `docs/contributing-guide` + +### 3. Make Your Changes + +```bash +# Install dependencies +npm install + +# Run the dev server +npm run dev + +# Run type checking +npm run typecheck --workspace @codenomad/ui +``` + +### 4. Commit + +Write clear, descriptive commit messages. Explain **what** changed and **why**. + +```bash +git add . +git commit -m "fix(ui): preserve question queue order when upserting duplicate requests + +When a question arrives as a global entry and later resolves to a tool +part with a newer timestamp, the original enqueue time was lost, causing +the question to move behind newer entries and break interruption order." +``` + +### 5. Push and Create a PR + +```bash +git push origin your-branch-name +``` + +Then open a pull request on GitHub targeting the `dev` branch. + +**PR checklist:** +- [ ] Branch is based on latest `upstream/dev` +- [ ] One issue per PR (don't mix unrelated changes) +- [ ] `npm run typecheck --workspace @codenomad/ui` passes +- [ ] Tests pass (if applicable) +- [ ] PR description explains the change and links the issue + +## Project Structure + +| Package | Description | +|---|---| +| `packages/server` | Core logic & CLI — workspaces, OpenCode proxy, API, auth | +| `packages/ui` | SolidJS frontend — reactive UI components and stores | +| `packages/electron-app` | Electron desktop shell | +| `packages/tauri-app` | Tauri desktop shell (experimental) | + +### Key UI Files + +| Path | Purpose | +|---|---| +| `packages/ui/src/stores/session-events.ts` | SSE event handlers (idle, status, permissions, questions) | +| `packages/ui/src/stores/session-actions.ts` | User actions (send message, abort, revert, fork) | +| `packages/ui/src/stores/message-v2/` | Message store (v2 architecture) | +| `packages/ui/src/stores/instances.ts` | Instance management and interruption queues | +| `packages/ui/src/components/tool-call.tsx` | Tool call rendering | +| `packages/ui/src/components/message-block.tsx` | Message display blocks | +| `packages/ui/src/components/session/session-view.tsx` | Main session view | +| `packages/ui/src/lib/i18n/messages/` | Translation files (en, es, fr, ja, ru, he, zh-Hans) | + +### Styling + +- Tokens: `src/styles/tokens.css` +- Utilities: `src/styles/utilities.css` +- Component styles: `src/styles/components/`, `src/styles/messaging/`, `src/styles/panels/` +- Keep style files under ~150 lines; split by component + +### Internationalization (i18n) + +- Use `useI18n()` in components, `tGlobal()` in stores +- Messages live in `packages/ui/src/lib/i18n/messages//` +- When adding a string: add to `en/` first, then add the same key to every other locale +- Placeholders use `{name}` syntax (word characters only) + +## Code Principles + +- **KISS**: Keep modules narrowly scoped +- **DRY**: Share helpers before copy-pasting +- **Single responsibility**: Split files when concerns diverge +- **Composable primitives**: Prefer signals, hooks, utilities over deep inheritance + +## Need Help? + +- Check existing [issues](https://github.com/NeuralNomadsAI/CodeNomad/issues) and [PRs](https://github.com/NeuralNomadsAI/CodeNomad/pulls) +- Ask in the issue you're working on +- Review the [server documentation](packages/server/README.md) for CLI flags and configuration From 2e60b38bfcfe0c6724decb8549c18306b23f6f77 Mon Sep 17 00:00:00 2001 From: JD Date: Tue, 26 May 2026 18:19:29 +0000 Subject: [PATCH 2/5] fix: address review feedback on project structure, paths, and prerequisites - Add missing packages/opencode-plugin and packages/cloudflare to the package table. - Replace hardcoded Key UI Files table with a pointer to the codenomad-architecture-guide skill for maintainability. - Fix styling paths to use packages/ui/src/styles/... (repo-root relative) instead of src/styles/... - Add Prerequisites section (Node.js 18+, OpenCode CLI in PATH) before Quick Start. - Broaden typecheck guidance in PR checklist to recommend root or area-specific scripts. --- CONTRIBUTING.md | 31 ++++++++++++++----------------- 1 file changed, 14 insertions(+), 17 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5caec4a4a..ef70f5b17 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,6 +2,11 @@ Thank you for your interest in contributing! This guide will help you get started. +## Prerequisites + +- **Node.js 18+** and npm +- **OpenCode CLI** in your `PATH` (the server connects to the OpenCode binary to manage workspaces) + ## Quick Start ```bash @@ -90,37 +95,29 @@ Then open a pull request on GitHub targeting the `dev` branch. **PR checklist:** - [ ] Branch is based on latest `upstream/dev` - [ ] One issue per PR (don't mix unrelated changes) -- [ ] `npm run typecheck --workspace @codenomad/ui` passes +- [ ] Type checking passes: `npm run typecheck` (root) or the workspace-specific script matching your change area - [ ] Tests pass (if applicable) - [ ] PR description explains the change and links the issue ## Project Structure | Package | Description | -|---|---| +|---|---|---| | `packages/server` | Core logic & CLI — workspaces, OpenCode proxy, API, auth | | `packages/ui` | SolidJS frontend — reactive UI components and stores | | `packages/electron-app` | Electron desktop shell | | `packages/tauri-app` | Tauri desktop shell (experimental) | +| `packages/opencode-plugin` | OpenCode plugin integration | +| `packages/cloudflare` | Cloudflare deployment adapters | -### Key UI Files - -| Path | Purpose | -|---|---| -| `packages/ui/src/stores/session-events.ts` | SSE event handlers (idle, status, permissions, questions) | -| `packages/ui/src/stores/session-actions.ts` | User actions (send message, abort, revert, fork) | -| `packages/ui/src/stores/message-v2/` | Message store (v2 architecture) | -| `packages/ui/src/stores/instances.ts` | Instance management and interruption queues | -| `packages/ui/src/components/tool-call.tsx` | Tool call rendering | -| `packages/ui/src/components/message-block.tsx` | Message display blocks | -| `packages/ui/src/components/session/session-view.tsx` | Main session view | -| `packages/ui/src/lib/i18n/messages/` | Translation files (en, es, fr, ja, ru, he, zh-Hans) | +> For a complete navigation guide covering all six functional areas (server, UI, desktop, speech/audio, build, Cloudflare), SDK integration patterns, and feature traces, load the `codenomad-architecture-guide` skill in your agent: +> `.opencode/skills/codenomad-architecture-guide/SKILL.md` ### Styling -- Tokens: `src/styles/tokens.css` -- Utilities: `src/styles/utilities.css` -- Component styles: `src/styles/components/`, `src/styles/messaging/`, `src/styles/panels/` +- Tokens: `packages/ui/src/styles/tokens.css` +- Utilities: `packages/ui/src/styles/utilities.css` +- Component styles: `packages/ui/src/styles/components/`, `packages/ui/src/styles/messaging/`, `packages/ui/src/styles/panels/` - Keep style files under ~150 lines; split by component ### Internationalization (i18n) From 86b5721bc40d1a54ec72d9fbe044727f0a74ae44 Mon Sep 17 00:00:00 2001 From: JD Date: Tue, 26 May 2026 18:26:28 +0000 Subject: [PATCH 3/5] fix: restore key UI files table until architecture skill PR lands The reviewer recommended keeping the file list available as a supplement until PR #493 (codenomad-architecture-guide skill) is merged, since the skill file does not exist in this branch yet. --- CONTRIBUTING.md | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ef70f5b17..60ec42fe2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -110,8 +110,21 @@ Then open a pull request on GitHub targeting the `dev` branch. | `packages/opencode-plugin` | OpenCode plugin integration | | `packages/cloudflare` | Cloudflare deployment adapters | -> For a complete navigation guide covering all six functional areas (server, UI, desktop, speech/audio, build, Cloudflare), SDK integration patterns, and feature traces, load the `codenomad-architecture-guide` skill in your agent: -> `.opencode/skills/codenomad-architecture-guide/SKILL.md` +### Key UI Files + +| Path | Purpose | +|---|---| +| `packages/ui/src/stores/session-events.ts` | SSE event handlers (idle, status, permissions, questions) | +| `packages/ui/src/stores/session-actions.ts` | User actions (send message, abort, revert, fork) | +| `packages/ui/src/stores/message-v2/` | Message store (v2 architecture) | +| `packages/ui/src/stores/instances.ts` | Instance management and interruption queues | +| `packages/ui/src/components/tool-call.tsx` | Tool call rendering | +| `packages/ui/src/components/message-block.tsx` | Message display blocks | +| `packages/ui/src/components/session/session-view.tsx` | Main session view | +| `packages/ui/src/lib/i18n/messages/` | Translation files (en, es, fr, ja, ru, he, zh-Hans) | + +> For a comprehensive map of all six functional areas (server, UI, desktop, speech/audio, build, Cloudflare), SDK integration patterns, and feature traces, load the `codenomad-architecture-guide` skill: +> `.opencode/skills/codenomad-architecture-guide/SKILL.md` (available after [PR #493](https://github.com/NeuralNomadsAI/CodeNomad/pull/493) lands) ### Styling From 2df8c5d5bfbadb607fc7f1ea677d20447dd8a5c4 Mon Sep 17 00:00:00 2001 From: JD Date: Tue, 26 May 2026 19:08:39 +0000 Subject: [PATCH 4/5] fix: correct malformed table separator in project structure CodeNomadBot flagged that the 2-column Package/Description table had a 3-cell separator (|---|---|---|), which renders inconsistently. Fixed to |---|---| to match the number of columns. --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 60ec42fe2..4959b2c2f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -102,7 +102,7 @@ Then open a pull request on GitHub targeting the `dev` branch. ## Project Structure | Package | Description | -|---|---|---| +|---|---| | `packages/server` | Core logic & CLI — workspaces, OpenCode proxy, API, auth | | `packages/ui` | SolidJS frontend — reactive UI components and stores | | `packages/electron-app` | Electron desktop shell | From a5d38f54597f9dc67f597f359a46941962ffa1fa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pascal=20Andr=C3=A9?= Date: Sat, 13 Jun 2026 13:56:28 +0200 Subject: [PATCH 5/5] docs: refine contributing PR checklist --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4959b2c2f..968b54669 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -97,7 +97,7 @@ Then open a pull request on GitHub targeting the `dev` branch. - [ ] One issue per PR (don't mix unrelated changes) - [ ] Type checking passes: `npm run typecheck` (root) or the workspace-specific script matching your change area - [ ] Tests pass (if applicable) -- [ ] PR description explains the change and links the issue +- [ ] PR description explains the change, includes relevant screenshots for UI changes, and links related issues when applicable ## Project Structure @@ -124,7 +124,7 @@ Then open a pull request on GitHub targeting the `dev` branch. | `packages/ui/src/lib/i18n/messages/` | Translation files (en, es, fr, ja, ru, he, zh-Hans) | > For a comprehensive map of all six functional areas (server, UI, desktop, speech/audio, build, Cloudflare), SDK integration patterns, and feature traces, load the `codenomad-architecture-guide` skill: -> `.opencode/skills/codenomad-architecture-guide/SKILL.md` (available after [PR #493](https://github.com/NeuralNomadsAI/CodeNomad/pull/493) lands) +> `.opencode/skills/codenomad-architecture-guide/SKILL.md` ### Styling