docs: enhance contributing docs by adityachoudhari26 · Pull Request #1006 · ctrlplanedev/ctrlplane

adityachoudhari26 · 2026-04-16T23:27:10Z

Summary by CodeRabbit

Documentation
- Added comprehensive contribution guide covering project setup, development workflows, architecture overview, coding standards, testing expectations, and pull request guidelines
- Updated README with simplified quick-start instructions for local development using Docker Compose
- Created service-specific contribution documentation for API backend, web frontend, and reconciliation engine

coderabbitai · 2026-04-16T23:27:24Z

Warning

Rate limit exceeded

@adityachoudhari26 has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 48 minutes and 7 seconds before requesting another review.

Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 48 minutes and 7 seconds.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: c526668e-e9ac-41ed-bb1a-6e933e033e9d

📥 Commits

Reviewing files that changed from the base of the PR and between 161be35 and 896ff5a.

📒 Files selected for processing (2)

CONTRIBUTING.md
apps/workspace-engine/CONTRIBUTING.md

📝 Walkthrough

Walkthrough

This PR adds comprehensive contribution documentation for the Ctrlplane monorepo. It introduces a root-level CONTRIBUTING.md with development setup, architecture overview, coding standards, and testing guidelines, while adding service-specific contribution guides for the API, web, and workspace-engine applications. The README is refactored to reference the new CONTRIBUTING.md and streamline the quick-start snippet.

Changes

Cohort / File(s)	Summary
Root Documentation `CONTRIBUTING.md`, `README.md`	Introduces comprehensive root contribution guide covering setup, architecture, coding standards, testing, and PR workflow; refactors README to reference CONTRIBUTING.md and simplifies quick-start instructions.
Service-Specific Guides `apps/api/CONTRIBUTING.md`, `apps/web/CONTRIBUTING.md`, `apps/workspace-engine/CONTRIBUTING.md`	Adds service-focused contribution guides for Node/Express backend (REST/tRPC endpoints, webhooks, error handling), React frontend (routing, forms, state management, shadcn UI), and Go reconciliation engine (controllers, queue processing, lease-based locking).

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

docs: enhance contributing section in README #952: Related documentation restructuring that similarly modifies contributing and setup guidance in the repository.

Poem

🐰 From warren root to each app's door,
New guides show helpers what's in store,
With recipes and common traps laid bare,
The project thrives with documented care! 📚✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'docs: enhance contributing docs' directly summarizes the main change—adding and improving comprehensive contribution documentation across multiple service-specific guides and the root CONTRIBUTING.md file.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch enhance-contributing-docs

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Copilot

Pull request overview

Adds comprehensive contributing documentation across the monorepo, with a new root guide and per-service guides to help contributors understand architecture, workflows, and local development.

Changes:

Added new service-specific contributing guides for apps/api, apps/web, and apps/workspace-engine.
Added a new root CONTRIBUTING.md covering setup, repo structure, conventions, and testing.
Simplified the main README.md contributing section to point to the new root guide and provide a short quick start.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
apps/workspace-engine/CONTRIBUTING.md	New workspace-engine-specific architecture + controller recipes and local dev guidance.
apps/web/CONTRIBUTING.md	New web-app-specific stack, routing, and frontend development recipes.
apps/api/CONTRIBUTING.md	New API-service-specific OpenAPI/Express patterns, auth conventions, and e2e testing guidance.
README.md	Replaces the long contributing section with a link to the new guide + quick start snippet.
CONTRIBUTING.md	New root contributing guide consolidating setup, structure, conventions, and testing guidance.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-16T23:30:33Z

+```text
+apps/
+  api/                 # Node/Express REST + tRPC API — core business logic
+  web/                 # React 19 + React Router frontend


The repository structure omits apps/relay/, even though it exists in this repo. Adding it here would help contributors discover it (and aligns with the earlier note that Go is relevant beyond workspace-engine).

Suggested change

web/ # React 19 + React Router frontend

web/ # React 19 + React Router frontend

relay/ # Go relay service

Copilot · 2026-04-16T23:30:34Z

+  db/                  # Drizzle ORM schema + migrations (PostgreSQL)
+  trpc/                # tRPC server setup
+  auth/                # better-auth integration
+  workspace-engine-sdk/# Published TypeScript SDK for external integrations


Minor formatting typo in the code block path: there should be a space between the trailing slash and the # comment marker so it renders consistently with the other entries.

Suggested change

workspace-engine-sdk/# Published TypeScript SDK for external integrations

workspace-engine-sdk/ # Published TypeScript SDK for external integrations

Copilot · 2026-04-16T23:30:34Z

@@ -0,0 +1,437 @@
+# Contributing to `apps/workspace-engine`
+
+This is the service guide for `apps/workspace-engine` — the Go reconciliation engine that turns user intent (a new version, a changed selector, a policy update) into concrete jobs dispatched to job agents. It assumes you've completed the root [CONTRIBUTING.md](../../CONTRIBUTING.md) setup and can run `pnpm dev` or `go run ./...` in this directory.


go run ./... from apps/workspace-engine is likely to fail because this module contains multiple package main entrypoints (e.g. main.go and tools/seed/seed.go). Use go run . (or pnpm dev / pnpm start) to run the service binary from this directory.

Suggested change

This is the service guide for `apps/workspace-engine` — the Go reconciliation engine that turns user intent (a new version, a changed selector, a policy update) into concrete jobs dispatched to job agents. It assumes you've completed the root [CONTRIBUTING.md](../../CONTRIBUTING.md) setup and can run `pnpm dev` or `go run ./...` in this directory.

This is the service guide for `apps/workspace-engine` — the Go reconciliation engine that turns user intent (a new version, a changed selector, a policy update) into concrete jobs dispatched to job agents. It assumes you've completed the root [CONTRIBUTING.md](../../CONTRIBUTING.md) setup and can run `pnpm dev` or `go run .` in this directory.

Copilot · 2026-04-16T23:30:34Z

+├── oapi/                      # OpenAPI-generated types (shared domain objects)
+├── pkg/
+│   ├── config/                # env var config (incl. SERVICES filter)
+│   ├── db/                    # pgx pool, sqlc-generated queries
+│   ├── oapi/                  # Domain types (Deployment, Release, etc.)


The directory layout description for oapi/ looks inaccurate: in this repo apps/workspace-engine/oapi/ contains the OpenAPI spec inputs/output (spec/, cfg.yaml, openapi.json), while the generated Go types live under pkg/oapi/ (e.g. pkg/oapi/oapi.gen.go). Consider updating these two lines to avoid sending contributors to the wrong directory.

Suggested change

├── oapi/ # OpenAPI-generated types (shared domain objects)

├── pkg/

│ ├── config/ # env var config (incl. SERVICES filter)

│ ├── db/ # pgx pool, sqlc-generated queries

│ ├── oapi/ # Domain types (Deployment, Release, etc.)

├── oapi/ # OpenAPI spec inputs/output (spec/, cfg.yaml, openapi.json)

├── pkg/

│ ├── config/ # env var config (incl. SERVICES filter)

│ ├── db/ # pgx pool, sqlc-generated queries

│ ├── oapi/ # Generated Go OpenAPI types (for example, oapi.gen.go)

Copilot · 2026-04-16T23:30:35Z

+| ------- | ------------ | -------------------------------------------------- |
+| Node.js | `>= 22.10.0` | Managed by Flox, or install directly               |
+| pnpm    | `^10.2.0`    | Managed by Flox, or install directly               |
+| Go      | `1.26+`      | Only needed for `workspace-engine`                 |


The prerequisites table says Go is only needed for workspace-engine, but this repo also has apps/relay (a Go module). Please include relay here (or adjust the note) so contributors don't skip installing Go when working on relay.

Suggested change

| Go | `1.26+` | Only needed for `workspace-engine` |

| Go | `1.26+` | Needed for `workspace-engine` and `apps/relay` |

Copilot · 2026-04-16T23:30:35Z

+
+```bash
+cd apps/workspace-engine
+go run ./...                         # Run without building


In the workspace-engine commands snippet, go run ./... is likely to error because ./... expands to multiple packages (and there are multiple package main entrypoints under apps/workspace-engine, including tools/seed). Prefer go run . for running the service from this directory.

Suggested change

go run ./... # Run without building

go run . # Run without building

Copilot · 2026-04-16T23:30:35Z

+By default `workspace-engine` runs all controllers. To run a subset (useful when debugging one), set `SERVICES` in `.env`:
+
+```bash
+SERVICES=deploymentplan,policyeval


The SERVICES example uses deploymentplan,policyeval, but the actual controller kind names include hyphens (e.g. deployment-plan and policy-eval from pkg/reconcile/events/*). Since IsServiceEnabled does an exact string match, this example won't work as written.

Suggested change

SERVICES=deploymentplan,policyeval

SERVICES=deployment-plan,policy-eval

docs: enhance contributing docs

161be35

Copilot AI review requested due to automatic review settings April 16, 2026 23:27

Copilot started reviewing on behalf of adityachoudhari26 April 16, 2026 23:27 View session

Copilot AI reviewed Apr 16, 2026

View reviewed changes

cleanup

896ff5a

adityachoudhari26 merged commit afc753a into main Apr 16, 2026
13 checks passed

adityachoudhari26 deleted the enhance-contributing-docs branch April 16, 2026 23:39

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: enhance contributing docs#1006

docs: enhance contributing docs#1006
adityachoudhari26 merged 2 commits intomainfrom
enhance-contributing-docs

adityachoudhari26 commented Apr 16, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Apr 16, 2026 •

edited

Loading

Rate limit exceeded

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Poem

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 16, 2026

Uh oh!

Copilot AI Apr 16, 2026

Uh oh!

Copilot AI Apr 16, 2026

Uh oh!

Copilot AI Apr 16, 2026

Uh oh!

Copilot AI Apr 16, 2026

Uh oh!

Copilot AI Apr 16, 2026

Uh oh!

Copilot AI Apr 16, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	web/ # React 19 + React Router frontend
	web/ # React 19 + React Router frontend
	relay/ # Go relay service

	workspace-engine-sdk/# Published TypeScript SDK for external integrations
	workspace-engine-sdk/ # Published TypeScript SDK for external integrations

		@@ -0,0 +1,437 @@
		# Contributing to `apps/workspace-engine`

		This is the service guide for `apps/workspace-engine` — the Go reconciliation engine that turns user intent (a new version, a changed selector, a policy update) into concrete jobs dispatched to job agents. It assumes you've completed the root [CONTRIBUTING.md](../../CONTRIBUTING.md) setup and can run `pnpm dev` or `go run ./...` in this directory.

	\| Go \| `1.26+` \| Only needed for `workspace-engine` \|
	\| Go \| `1.26+` \| Needed for `workspace-engine` and `apps/relay` \|

	go run ./... # Run without building
	go run . # Run without building

	SERVICES=deploymentplan,policyeval
	SERVICES=deployment-plan,policy-eval

Conversation

adityachoudhari26 commented Apr 16, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Apr 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Rate limit exceeded

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Poem

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

adityachoudhari26 commented Apr 16, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Apr 16, 2026 •

edited

Loading