Contributing

Orchestra is a monorepo, consolidated in 2026-04 from the legacy separate repos. This page covers how changes land: where code lives, how to name branches and commits, and the review workflow.

Before you start, get the stack running locally — see Local Development.

Repository layout

Path	What it is
`operator/`	Kubernetes operator — manages Workshop CRDs and lifecycle
`server/`	Orchestra API (FastAPI) — REST endpoints for workshop ops
`frontend/`	Web dashboard (React)
`sidecar/`	Per-pod auth/proxy sidecar (Go)
`deploy/`	Helm charts and Kubernetes manifests
`docs/`	This documentation site (Astro / Starlight)

The repo is driven by a justfile at the root — just setup, just dev, just test, just quality. See Local Development for the full dev loop.

Branch naming

Work happens on feature branches, never directly on main. Name branches type/short-description, using the same type vocabulary as commits:

feat/workshop-env-args
fix/workshop-phase-enums
docs/gke-standard-plan
refactor/...
chore/add-claude-md

Commit messages

Orchestra uses Conventional Commits: type(scope): summary. The types and scopes already in use across the history:

Type	Used for
`feat`	New functionality
`fix`	Bug fixes
`docs`	Documentation changes
`chore`	Tooling, deps, housekeeping
`refactor`	Code restructuring with no behavior change
`test`	Test additions or changes

Common scopes seen in the log: api, operator, frontend, deploy, docs, landing, user-guide, adr, cloudflare. Pick the scope that matches the area you touched; combined scopes (e.g. test+docs:) are fine when a change genuinely spans two.

Examples from the history:

feat(operator): apply template env/args to the workshop pod
fix(api): add Starting/Terminated to WorkshopPhase enum (status-sync crash)
docs(adr): ADR-0005 GKE Standard with config-driven tenant pools
chore(frontend): clear pre-existing eslint warnings

Pull request workflow

Branch off main using the type/short-description convention.
Commit in small, well-described chunks — prefer several focused commits over one large unreviewable one.
Open a PR against main on GitHub.
Review — at least one reviewer. Active collaborators are Vince Carey and Alex Mahmoud.
Merge via a GitHub merge commit. Do not rebase — history is preserved with merge commits (the log shows Merge pull request #N from ...), which keeps the true sequence of events and stays reversible.

Bring upstream changes into your branch with git merge origin/main, not git pull --rebase.

Review checklist

Before requesting review (and before merging), confirm:

Tests pass. Run just test for the full monorepo suite. See the Testing guide for the three test tiers and where to add coverage.
Quality passes. Run just quality (ruff for Python, eslint/prettier for JS/TS, go fmt for the sidecar).
Docs updated. If the change affects behavior, configuration, or the public API, update the relevant page under docs/.
Types regenerated. If you changed API models, run just sync-types so the frontend’s generated types stay in sync.
ADR added for architectural decisions. Record significant or hard-to-reverse decisions as an Architecture Decision Record under docs/adr/, following the numbered format of the existing records (e.g. ADR-0005).