vrr/CodeNomad
2
0
Fork 0
mirror of https://github.com/NeuralNomadsAI/CodeNomad.git synced 2026-07-09 16:00:52 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1
CodeNomad/CONTRIBUTING.md
Dark 17547a15d8
docs: add CONTRIBUTING.md guide for new contributors (#484) 
## Summary
Adds a CONTRIBUTING.md file to help new contributors get started.

## Contents
- 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.

---------
2026-06-13 14:01:04 +02:00

5.1 KiB
Raw Blame History

Contributing to CodeNomad

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

git clone https://github.com/NeuralNomadsAI/CodeNomad.git
cd CodeNomad
npm install
npm run dev

Finding Issues to Work On

Browse open 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

# 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

# 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.

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

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)
  • 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, includes relevant screenshots for UI changes, and links related issues when applicable

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 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

Styling

  • 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)

  • Use useI18n() in components, tGlobal() in stores
  • Messages live in packages/ui/src/lib/i18n/messages/<locale>/
  • 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?