Contributing to OrchestCode

Getting Started

Clone the repository, install dependencies, and start the development server:

git clone https://github.com/orchestcode/orchestcode.git
cd orchestcode
pnpm install
pnpm dev

The site runs on Next.js with static export. All content lives alongside the code in the same monorepo. You do not need any API keys or external services to work on the site.

Issue Labels

We use labels to categorize issues and help contributors find work that matches their skills:

• bug
  Something is broken or behaving unexpectedly. Include steps to reproduce when filing.
• feature
  A new capability or enhancement. Describe the use case and expected behavior.
• content
  Improvements to chapter text, diagrams, examples, or explanations. Great for first-time contributors.
• a11y
  Accessibility improvements: screen reader support, keyboard navigation, color contrast, and semantic markup.

PR Guidelines

Branch Naming

Use descriptive branch names that include the issue type and a short summary:

fix/broken-link-ch04
feat/add-trace-export
content/ch07-worktree-diagram
a11y/keyboard-nav-glossary

Commit Format

Write clear, imperative commit messages. Start with a verb. Keep the first line under 72 characters. Add detail in the body if needed.

fix: resolve broken anchor links on glossary page

The hash links were using camelCase but the IDs were lowercase.
Updated all related entries to use consistent casing.

Review Process

Every PR requires at least one review before merging. Reviewers check for correctness, clarity, and consistency with existing content. Be patient and open to feedback — it is part of the collaborative process.

Content Style Guide

OrchestCode content follows a consistent voice and structure:

• Chapter Template
  Each chapter opens with a “Why This Matters” section, followed by concept explanations, code examples, and a summary. Follow the existing chapter structure when adding new content.
• Tone
  Direct, clear, and welcoming. Explain concepts as if speaking to a capable colleague who is new to the topic. Avoid jargon without explanation. Do not use filler phrases.
• Code Conventions
  All code examples use TypeScript. Keep examples minimal and focused on the concept being taught. Add inline comments only where the logic is non-obvious.

Code Style

The codebase follows these conventions:

• TypeScript Strict
  All code is written in TypeScript with strict mode enabled. No any types unless absolutely necessary and documented.
• ESM
  The project uses ES modules exclusively. Use import and export syntax. No CommonJS require calls.
• CSS Modules
  All component styles use CSS Modules (.module.css). No global styles outside of globals.css. Use the existing design tokens (CSS custom properties) for spacing, colors, and typography.