From 28d503b10aa6b35aa9aa596e66cc9dbc4225a159 Mon Sep 17 00:00:00 2001 From: Yukti Nandwana Date: Fri, 15 May 2026 18:58:19 +0530 Subject: [PATCH 1/5] docs: update CONTRIBUTING.md with local setup and PR guidelines --- CONTRIBUTING.md | 470 ++++++++++++++---------------------------------- 1 file changed, 131 insertions(+), 339 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e8677ab..386df23 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,434 +2,226 @@ Welcome. This guide gets you from `git clone` to a running local app, then walks you through opening your first PR. Should take 15-20 minutes the first time. -Works the same on **macOS**, **Linux**, and **Windows (WSL2)**. Native Windows isn't supported - Supabase CLI has known issues outside WSL2. - -**Got a question before you start? Join the conversation on [GitHub Discussions](https://github.com/Coder-s-OG-s/MergeShip/discussions) - introductions, setup help, feature ideas, anything.** +Works the same on **macOS**, **Linux**, and **Windows (WSL2)**. Native Windows isn't supported — Supabase CLI has known issues outside WSL2. --- ## 1. Prerequisites -Install these once: +Install these once before starting: -| Tool | Version | Notes | -| ------- | --------------- | ----------------------------------------------------------------------------------------------- | -| Node.js | 20 LTS or newer | Use [nvm](https://github.com/nvm-sh/nvm) or [nodejs.org](https://nodejs.org). Verify: `node -v` | -| npm | 10+ | Comes with Node. Don't use pnpm or yarn — the lockfile is npm. | -| Docker | latest | Docker Desktop on macOS/Windows, `docker.io` on Linux | -| Git | any modern | `git --version` | +| Tool | Version | Notes | +| --- | --- | --- | +| Node.js | 20 LTS or newer | Use nvm or nodejs.org. Verify: `node -v` | +| pnpm | latest | Package manager required for this project. Install via `npm install -g pnpm` | +| Docker | latest | Docker Desktop on macOS/Windows, `docker.io` on Linux | +| Supabase CLI | latest | Used for local database and auth testing | +| Git | any modern | Verify: `git --version` | ### Platform-specific setup **macOS:** - -- Install Docker Desktop from [docker.com](https://www.docker.com/products/docker-desktop). On Apple Silicon (M1/M2/M3) it runs native arm64 — no flags needed. -- Make sure Docker Desktop is **running** (icon in menu bar) before you start anything below. +- Install Docker Desktop. On Apple Silicon (M1/M2/M3) it runs native arm64. +- Make sure Docker Desktop is **running** before you start. **Windows:** - -- Install [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) first (`wsl --install` in PowerShell, then reboot). -- Install Docker Desktop and enable the WSL2 backend in **Settings → General**. -- Run **all commands below from inside the WSL2 Ubuntu shell**, not PowerShell or CMD. -- Install Node + npm inside WSL2 (`sudo apt install nodejs npm` or use nvm inside WSL2). - -**Linux:** - -- Install Docker via your distro (`sudo apt install docker.io` on Ubuntu). -- Add yourself to the `docker` group so you don't need `sudo`: `sudo usermod -aG docker $USER`, then log out and back in. - -### What you do NOT need - -- A GitHub OAuth App -- A GitHub App -- A smee.io tunnel -- An Inngest, Groq, Sentry, or PostHog account -- A real Redis (in-memory fallback ships with the repo) - -For 95% of contributor work, you only need the steps below. +- Install WSL2 (`wsl --install` in PowerShell, then reboot). +- Install Docker Desktop and enable the WSL2 backend in Settings → General. +- Run **all commands below from inside the WSL2 Ubuntu shell**. --- -## 2. Local setup (5 commands) +## 2. Local setup (Step-by-step) ```bash -git clone https://github.com/Coder-s-OG-s/MergeShip.git +git clone [https://github.com/Coder-s-OG-s/MergeShip.git](https://github.com/Coder-s-OG-s/MergeShip.git) cd MergeShip -npm install +pnpm install cp .env.example .env.local -``` - -Then start the local Supabase stack. **First run pulls ~2.5GB of Docker images and takes 5-10 minutes.** Subsequent starts are ~30 seconds. -```bash +Then start the local Supabase stack. First run pulls ~2.5GB of Docker images and takes 5-10 minutes. make supabase-start -``` -When it finishes, it prints URLs and keys. You need two keys from the output (or run `npx supabase status -o env` to print them again): +Apply migrations + seed dev personas: +make db-reset -- `ANON_KEY` → paste into `.env.local` as `NEXT_PUBLIC_SUPABASE_ANON_KEY` -- `SERVICE_ROLE_KEY` → paste into `.env.local` as `SUPABASE_SERVICE_ROLE_KEY` +Start the dev server: +pnpm dev -Then apply migrations + seed dev personas: +App is live at http://localhost:3001. -```bash -make db-reset -``` +Koi baat nahi Yukti, hota hai! Panic mein aksar Cmd + A aur Delete dab hi jata hai. 😂 -Start the dev server: +Main niche poora final code wapas de raha hoon. Is baar ekdum dhyan se copy karna (code block ke top-right corner mein Copy icon use karna) aur use apni CONTRIBUTING.md mein paste karke save kar do. -```bash -npm run dev -``` +Markdown +# Contributing to MergeShip -App is live at **http://localhost:3001**. +Welcome. This guide gets you from `git clone` to a running local app, then walks you through opening your first PR. Should take 15-20 minutes the first time. + +Works the same on **macOS**, **Linux**, and **Windows (WSL2)**. Native Windows isn't supported — Supabase CLI has known issues outside WSL2. --- -## 3. Sign in +## 1. Prerequisites -Open **http://localhost:3001/dev/login** and click any of the six seeded personas: +Install these once before starting: -| Persona | Level | What they have | -| ------- | ---------- | ----------------------------------------- | -| Alice | L0 | Brand new account, no audit yet | -| Bob | L1 | Audited, has active recommendations | -| Carol | L2 | 3 merges, mentor-eligible | -| Dave | L3 | Mentor with 5 mentees, sees `/maintainer` | -| Eve | L4 | Senior mentor, sees `/maintainer` | -| Frank | Maintainer | Owns demo/sample-repo, sees `/maintainer` | +| Tool | Version | Notes | +| --- | --- | --- | +| Node.js | 20 LTS or newer | Use nvm or nodejs.org. Verify: `node -v` | +| pnpm | latest | Package manager required for this project. Install via `npm install -g pnpm` | +| Docker | latest | Docker Desktop on macOS/Windows, `docker.io` on Linux | +| Supabase CLI | latest | Used for local database and auth testing | +| Git | any modern | Verify: `git --version` | -Click a button → instant sign-in via Supabase email/password (no real OAuth needed). The `/dev/login` page returns 404 in production builds. +### Platform-specific setup + +**macOS:** +- Install Docker Desktop. On Apple Silicon (M1/M2/M3) it runs native arm64. +- Make sure Docker Desktop is **running** before you start. + +**Windows:** +- Install WSL2 (`wsl --install` in PowerShell, then reboot). +- Install Docker Desktop and enable the WSL2 backend in Settings → General. +- Run **all commands below from inside the WSL2 Ubuntu shell**. --- -## 4. Daily commands +## 2. Local setup (Step-by-step) ```bash -make supabase-start # start local Postgres/Auth (idempotent) -npm run dev # dev server on :3001 with hot reload -make supabase-stop # shut down containers when done +git clone [https://github.com/Coder-s-OG-s/MergeShip.git](https://github.com/Coder-s-OG-s/MergeShip.git) +cd MergeShip +pnpm install +cp .env.example .env.local +Then start the local Supabase stack. First run pulls ~2.5GB of Docker images and takes 5-10 minutes. -make db-reset # nuke + re-apply migrations + reseed personas -make test # run all tests -make test-watch # TDD mode -make typecheck # tsc --noEmit -make lint # eslint -make format # prettier --write -``` +Bash +make supabase-start +Apply migrations + seed dev personas: ---- +Bash +make db-reset +Start the dev server: -## 5. Repo layout - -``` -src/ - app/ - (app)/ # authenticated routes (dashboard, leaderboard, maintainer) - [handle]/ # public profile pages /@username - api/ # auth callback, github webhook, inngest endpoint - actions/ # server actions, one file per domain - dev/login/ # dev-only persona switcher - lib/ - cache/ # redis or in-memory fallback - db/ # drizzle schema + client - github/ # octokit factories, webhook hmac - help/ # help-routing logic - llm/ # groq router - maintainer/ # PR queue, issue triage, mentor flow - pipeline/ # difficulty scoring, rec ranking - supabase/ # supabase clients (browser / server / service-role) - xp/ # curve, events, caps, audit, sources, streak - inngest/ - client.ts - functions/ # background jobs -supabase/ - migrations/ # numbered SQL migrations -scripts/ - seed.ts # synthetic personas - sim-webhook.ts # fire mock webhook -``` - -Most contributor PRs only touch `src/app/`, `src/lib/`, or `src/app/actions/`. +Bash +pnpm dev +App is live at http://localhost:3001. ---- +3. Environment Variables Explanation (.env.example) +Your .env.local file requires specific keys to function properly. Here is what each variable does and where to get it: -## 6. Picking what to work on +NEXT_PUBLIC_SUPABASE_ANON_KEY: Public key for Supabase client. You get this from the terminal output after running make supabase-start or by running npx supabase status -o env. -1. Browse [issues labeled `good-first-issue`](https://github.com/Coder-s-OG-s/MergeShip/issues?q=is%3Aissue+is%3Aopen+label%3Agood-first-issue) or `gssoc`. -2. Comment "I'd like to work on this" before starting. -3. Wait for an assignment to avoid duplicate work. +SUPABASE_SERVICE_ROLE_KEY: Admin key for server-side Supabase operations. Found in the same terminal output mentioned above. -**Claim limit: maximum 3 issues at a time.** +GITHUB_APP_ID, GITHUB_APP_CLIENT_ID, GITHUB_APP_CLIENT_SECRET, GITHUB_APP_PRIVATE_KEY: Required for GitHub webhook integration. You generate these by creating a GitHub App in your developer settings (See Section 12). -If you already have 3 open issues assigned or 3 open PRs, you must get them merged or closed before picking up anything new. A bot will automatically unassign you and leave a comment if you go over the limit. This keeps issues available for others and prevents hoarding. +GITHUB_WEBHOOK_SECRET: A custom random string you set when configuring your GitHub App webhooks. ---- +4. Sign in +Open http://localhost:3001/dev/login and click any seeded persona (Alice, Bob, etc.) for instant sign-in. The /dev/login page returns 404 in production builds. -## 7. PR workflow +5. Daily commands + +make supabase-start # start local Postgres/Auth +pnpm dev # dev server on :3001 with hot reload +make supabase-stop # shut down containers + +make db-reset # nuke + re-apply migrations + reseed personas +make test # run all tests +make typecheck # tsc --noEmit +make lint # eslint +make format # prettier --write + +6. PR workflow & Guidelines -```bash # 1. Sync main git checkout main git pull origin main -# 2. Branch -git checkout -b feat/short-name # also: fix/, chore/, docs/, refactor/ +# 2. Branch naming conventions +# Use descriptive prefixes: fix/issue-name or feat/feature-name +git checkout -b feat/short-name -# 3. Make changes + tests, then verify +# 3. Verify changes make test make typecheck make lint -# 4. Commit (one logical change per commit) -git add # not `git add .` -git commit # pre-commit hook runs prettier + eslint +# 4. Commit format +# Use conventional commits: fix: description or feat: description +git add +git commit # 5. Push + open PR git push -u origin feat/short-name -``` - -Open the PR via the GitHub web UI or `gh pr create`. -PR title follows [conventional commits](https://www.conventionalcommits.org/): `feat(scope): ...`, `fix(scope): ...`, `chore: ...`, `test: ...`, `docs: ...`, `refactor: ...`. - -PR body must include: what changed, why, test plan, and `Closes #N`. - ---- +PR title must follow conventional commits. PR body must include: what changed, why, and Closes #N. -## 8. By the type of change you're making +7. Code style — non-negotiable +Tailwind Only: Strictly use Tailwind classes for styling. No custom CSS. -### A. UI tweak / new page +No emojis: Do not use emojis in the codebase or commit messages. -1. Find or create the file under `src/app/(app)/` or `src/components/`. -2. Edit and watch it hot-reload at localhost:3001. -3. Test with different personas via `/dev/login` to cover L0/L1/L2/maintainer states. -4. Tests not strictly required for UI but encouraged for logic. +Minimal comments: Write self-documenting code. No comments unless absolutely necessary for complex logic. -### B. New server action +No any — use unknown + narrowing. -1. Add it to an existing `src/app/actions/.ts` or create a new file. -2. First line of the file: `'use server'`. -3. Auth-check at top: `const { data: { user } } = await sb.auth.getUser(); if (!user) return err(...)`. -4. Wrap with `rateLimit({ namespace: '...', key: user.id, limit, windowSec })`. -5. Return a `Result` envelope: `ok(data)` or `err(code, message)`. -6. **Tests required.** Mock supabase, assert the result shape. +No console.log in committed code. -### C. Pure helper in `lib/` +File names: kebab-case.ts. Variables: camelCase. Types: PascalCase. SQL: snake_case. -1. Create `src/lib//your-thing.ts` and a `.test.ts` alongside it. -2. **TDD**: write the failing test first. -3. Keep it pure — no I/O, no DB, no fetch. -4. Coverage gate: `lib/` must stay ≥80%. -### D. New XP rule +8. By the type of change you're making +A. UI tweak / new page +Find or create the file under src/app/(app)/ or src/components/. Test with different personas via /dev/login. -1. Add to `XP_REWARDS` and `XP_SOURCE` in `src/lib/xp/sources.ts`. -2. Add `refIds.yourThing(...)` so the idempotency key is unique. -3. Add a cap in `src/lib/xp/caps.ts` if it's user-actionable. -4. Fire the event from where the action happens. -5. Tests required for cap + idempotency. +B. New server action +First line: 'use server'. Return a Result envelope. Tests required. -### E. New Inngest function +C. Pure helper in lib/ +Keep it pure — no I/O, no DB, no fetch. Coverage gate: lib/ must stay ≥80%. -1. Create `src/inngest/functions/your-function.ts`. -2. Wrap durable work in `step.run('name', async () => ...)`. -3. Use `concurrency: { key: 'event.data.', limit: 1 }` to prevent races. -4. Register in `src/app/api/inngest/route.ts`. -5. To run locally, start the Inngest dev server in another terminal: - ```bash - npx inngest-cli@latest dev - ``` - Functions auto-register from `/api/inngest`. UI at http://localhost:8288. +D. DB migration +Create supabase/migrations/000N_short_name.sql. Run make db-reset to verify. -### F. DB migration +9. Testing webhook handlers +The repo includes a webhook simulator that signs and POSTs synthetic payloads: -1. Create `supabase/migrations/000N_short_name.sql` (N = next number). -2. Use `if not exists` / `if exists` for safe reruns. -3. Mirror the columns/tables in `src/lib/db/schema.ts`. -4. RLS: every new table needs `enable row level security` + an explicit policy. -5. Run `make db-reset` to verify it applies cleanly. - -### G. Webhook handler change - -1. Edit the relevant file in `src/inngest/functions/process-*.ts`. -2. Test locally — see the next section. - -### H. Bug fix - -1. Reproduce locally first. -2. Write a failing test that captures the bug. -3. Fix the code, watch the test go green. - ---- - -## 9. Testing webhook handlers - -You do **not** need a real GitHub App. The repo includes a webhook simulator that signs and POSTs synthetic payloads: - -```bash npm run sim:webhook -- pr-merged --handle bob --repo demo/sample-repo --pr 123 -npm run sim:webhook -- review --handle dave --pr-url https://github.com/demo/sample-repo/pull/123 -npm run sim:webhook -- install --handle alice -``` - -The `--` is required to pass flags through npm. - -Two outcomes: - -- **Inngest dev server running** (`npx inngest-cli@latest dev`) → the function runs, you can verify DB state changed. -- **No Inngest dev server** → returns 202 with a log message. The webhook delivery row is still inserted; this is the right behavior for testing the route itself. - ---- - -## 10. Code style — non-negotiable - -- No `any` — use `unknown` + narrowing. -- No `console.log` in committed code. -- No emojis in code unless the user explicitly asked. -- Comments explain WHY, not WHAT. -- No `--no-verify` on commits — fix the lint issue instead. -- One PR = one logical change. -- File names: `kebab-case.ts`. Variables: `camelCase`. Types: `PascalCase`. SQL: `snake_case`. - -The pre-commit hook runs prettier + eslint. If it blocks your commit, fix the issue and re-commit — never bypass. - ---- - -## 11. Tests — required when - -| Touching | Tests required? | -| ------------------------ | --------------------------- | -| `src/lib/**` | Yes | -| `src/app/actions/**` | Yes | -| `src/inngest/**` | Yes | -| `supabase/migrations/**` | Yes (RLS or trigger tests) | -| `src/app/**` UI | Encouraged, reviewer's call | - -Coverage gate: `lib/` ≥ 80% lines. CI blocks merge if it drops. - ---- -## 12. Troubleshooting +10. Tests — required when -**`supabase: command not found`** -Run via `make supabase-start` or `npx supabase ...`. Don't install supabase globally. +Touching,Tests required? +src/lib/**,Yes +src/app/actions/**,Yes +src/inngest/**,Yes +supabase/migrations/**,Yes (RLS or trigger tests) -**`Cannot connect to the Docker daemon`** -Docker Desktop isn't running. Start it. On Linux: `sudo systemctl start docker`. +11. Troubleshooting +supabase: command not found: Run via make supabase-start. -**`supabase start` hangs** -First run pulls ~2.5GB of images. Wait 5-10 min. Stuck after 15 min: `Ctrl-C`, run `npx supabase stop`, then retry. +Cannot connect to the Docker daemon: Start Docker Desktop. -**Supabase containers crash / out of memory** -Docker Desktop → Settings → Resources → bump Memory to at least 4GB. +Port already in use: Kill the process using port 3001 or 54321. -**Port 54321 / 54322 / 54323 / 3001 already in use** -Another instance running. To free a port: +/dev/login returns 404: Ensure you are using pnpm dev. -- macOS/Linux: `lsof -ti:3001 | xargs kill` -- Windows (WSL2): `lsof -ti:3001 | xargs -r kill` +12. GitHub App setup instructions (Webhook integration) +If you need to test actual webhook delivery: -Another supabase project running? `npx supabase stop` from its directory. +Go to GitHub Developer Settings -> GitHub Apps -> New GitHub App. -**`SUPABASE_SERVICE_ROLE_KEY required` when running seed** -You haven't pasted the `service_role` key into `.env.local`. Run `npx supabase status -o env` and copy `SERVICE_ROLE_KEY`'s value into `SUPABASE_SERVICE_ROLE_KEY=...` in `.env.local`. +Homepage URL: http://localhost:3001 -**`/dev/login` returns 404** -You're in production mode. Use `npm run dev`, not `npm run build && npm start`. +Webhook URL: Use a tunneling service like smee.io. -**Persona button shows "Invalid credentials"** -The seed didn't run. `make db-seed`. +Webhook secret: Create a random string. -**"relation X already exists" on migration** -`make db-reset` wipes and reapplies cleanly. - -**Tests fail with "fetch failed" to Supabase** -Local Supabase isn't running. `make supabase-start`. - -**Prettier fails in CI but passes locally** -Run `make format` then commit. Usually a markdown file picked up formatter drift. - -**`npm install` peer dependency errors** -Only use npm (not pnpm/yarn). `rm -rf node_modules package-lock.json && npm install`. - -**`Cannot find module '@/lib/...'`** -VS Code: `Cmd/Ctrl+Shift+P` → "TypeScript: Select Version" → "Use Workspace Version". - -**Hot reload not working** -Restart `npm run dev`. Usually a circular import. - -**Cookie / session issues** -Use `http://localhost:3001`, not `127.0.0.1:3001`. Auth cookies are hostname-scoped. - -**Windows: CRLF line ending warnings** - -```bash -git config --global core.autocrlf input -``` - -**TypeScript error in a file you didn't touch** -Someone else's PR landed something that conflicts with your branch. Pull main and rebase. - ---- - -## 13. Advanced — testing with a real GitHub App - -Skip unless you need to debug actual webhook delivery from GitHub. Almost no PRs need this. - -1. https://github.com/settings/apps/new -2. Name: globally unique (e.g. `mergeship-dev-yourname`) -3. Homepage URL: `http://localhost:3001` -4. Webhook URL: a smee.io channel (generate at smee.io) -5. Webhook secret: a random string, save it -6. Permissions: Pull requests R+W, Issues R+W, Metadata R, Pull request review R -7. Subscribe: Pull request, Pull request review, Issues, Issue comment, Installation, Installation repositories -8. Generate + download private key (`.pem`) -9. Install on a test repo you own -10. Fill `.env.local`: - ``` - GITHUB_APP_ID= - GITHUB_APP_CLIENT_ID= - GITHUB_APP_CLIENT_SECRET= - GITHUB_APP_PRIVATE_KEY="" - GITHUB_WEBHOOK_SECRET= - MOCK_GITHUB_API=false - MOCK_GITHUB_WEBHOOKS=false - ``` -11. Terminal A: `npx smee-client --url https://smee.io/ --target http://localhost:3001/api/webhooks/github` -12. Terminal B: `npx inngest-cli@latest dev` -13. Trigger events on your test repo, watch them flow - ---- - -## 14. Security - -- Never commit `.env.local`, `.env`, `*.pem`, or any file with secrets. -- Never paste service role keys in issues or PRs. -- Never `git add .` blindly — stage specific files. -- Never bypass pre-commit hooks. - ---- - -## 15. Getting help - -1. Re-read the [Troubleshooting](#12-troubleshooting) section. -2. Search closed issues + PRs for your error. -3. **Post in [GitHub Discussions](https://github.com/Coder-s-OG-s/MergeShip/discussions)** - use the `Q&A` category for setup issues, `Ideas` for feature questions. Most setup questions get answered there within a day. -4. GSSoC contributors: drop in the cohort Discord channel. -5. Tag the maintainer only after the above. - -Include in any help request: - -- OS + Node version (`node -v`) -- Exact command that failed -- Full error text (paste it, not a screenshot) -- What you already tried - ---- +Generate and download the private key (.pem). -## 16. License +Update .env.local with the generated App ID, Client ID, Client Secret, Webhook Secret, and the exact contents of the PEM file. -By opening a PR you agree to license your contribution under the project's [MIT License](LICENSE). You retain copyright on your contribution. -We don't add AI-attribution footers to commits — author your work yourself. From 49668691179a85ad3bd7bcc886127dea6024ac69 Mon Sep 17 00:00:00 2001 From: Yukti Nandwana Date: Fri, 15 May 2026 20:32:14 +0530 Subject: [PATCH 2/5] style: fix formatting in CONTRIBUTING.md --- CONTRIBUTING.md | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 386df23..9d149f0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,21 +10,23 @@ Works the same on **macOS**, **Linux**, and **Windows (WSL2)**. Native Windows i Install these once before starting: -| Tool | Version | Notes | -| --- | --- | --- | -| Node.js | 20 LTS or newer | Use nvm or nodejs.org. Verify: `node -v` | -| pnpm | latest | Package manager required for this project. Install via `npm install -g pnpm` | -| Docker | latest | Docker Desktop on macOS/Windows, `docker.io` on Linux | -| Supabase CLI | latest | Used for local database and auth testing | -| Git | any modern | Verify: `git --version` | +| Tool | Version | Notes | +| ------------ | --------------- | ---------------------------------------------------------------------------- | +| Node.js | 20 LTS or newer | Use nvm or nodejs.org. Verify: `node -v` | +| pnpm | latest | Package manager required for this project. Install via `npm install -g pnpm` | +| Docker | latest | Docker Desktop on macOS/Windows, `docker.io` on Linux | +| Supabase CLI | latest | Used for local database and auth testing | +| Git | any modern | Verify: `git --version` | ### Platform-specific setup **macOS:** + - Install Docker Desktop. On Apple Silicon (M1/M2/M3) it runs native arm64. - Make sure Docker Desktop is **running** before you start. **Windows:** + - Install WSL2 (`wsl --install` in PowerShell, then reboot). - Install Docker Desktop and enable the WSL2 backend in Settings → General. - Run **all commands below from inside the WSL2 Ubuntu shell**. @@ -143,7 +145,7 @@ git pull origin main # 2. Branch naming conventions # Use descriptive prefixes: fix/issue-name or feat/feature-name -git checkout -b feat/short-name +git checkout -b feat/short-name # 3. Verify changes make test @@ -152,8 +154,8 @@ make lint # 4. Commit format # Use conventional commits: fix: description or feat: description -git add -git commit +git add +git commit # 5. Push + open PR git push -u origin feat/short-name @@ -225,3 +227,4 @@ Generate and download the private key (.pem). Update .env.local with the generated App ID, Client ID, Client Secret, Webhook Secret, and the exact contents of the PEM file. +``` From 26463ae6e2b936590a62fde8bbcc6af5f20e9b8d Mon Sep 17 00:00:00 2001 From: Yukti Nandwana Date: Fri, 15 May 2026 22:23:57 +0530 Subject: [PATCH 3/5] style: final prettier fix for contributing.md --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9d149f0..b10596f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -35,7 +35,7 @@ Install these once before starting: ## 2. Local setup (Step-by-step) -```bash +````bash git clone [https://github.com/Coder-s-OG-s/MergeShip.git](https://github.com/Coder-s-OG-s/MergeShip.git) cd MergeShip pnpm install @@ -227,4 +227,4 @@ Generate and download the private key (.pem). Update .env.local with the generated App ID, Client ID, Client Secret, Webhook Secret, and the exact contents of the PEM file. -``` +```` From 06976b7a4d1a3f71ae89e731e1221a22ccd250c0 Mon Sep 17 00:00:00 2001 From: Yukti Nandwana Date: Sat, 16 May 2026 16:16:21 +0530 Subject: [PATCH 4/5] docs: restore OS setups and discussion links as per review --- CONTRIBUTING.md | 467 ++++++++++++++++++++++++++++++++++-------------- 1 file changed, 334 insertions(+), 133 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b10596f..5d96b8f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,225 +6,426 @@ Works the same on **macOS**, **Linux**, and **Windows (WSL2)**. Native Windows i --- +**Got a question before you start? Join the conversation on [GitHub Discussions](https://github.com/Coder-s-OG-s/MergeShip/discussions) - introductions, setup help, feature ideas, anything.** + ## 1. Prerequisites -Install these once before starting: +Install these once: -| Tool | Version | Notes | -| ------------ | --------------- | ---------------------------------------------------------------------------- | -| Node.js | 20 LTS or newer | Use nvm or nodejs.org. Verify: `node -v` | -| pnpm | latest | Package manager required for this project. Install via `npm install -g pnpm` | -| Docker | latest | Docker Desktop on macOS/Windows, `docker.io` on Linux | -| Supabase CLI | latest | Used for local database and auth testing | -| Git | any modern | Verify: `git --version` | +| Tool | Version | Notes | +| ------- | --------------- | ----------------------------------------------------------------------------------------------- | +| Node.js | 20 LTS or newer | Use [nvm](https://github.com/nvm-sh/nvm) or [nodejs.org](https://nodejs.org). Verify: `node -v` | +| npm | 10+ | Comes with Node. Don't use pnpm or yarn — the lockfile is npm. | +| Docker | latest | Docker Desktop on macOS/Windows, `docker.io` on Linux | +| Git | any modern | `git --version` | ### Platform-specific setup **macOS:** -- Install Docker Desktop. On Apple Silicon (M1/M2/M3) it runs native arm64. -- Make sure Docker Desktop is **running** before you start. +- Install Docker Desktop from [docker.com](https://www.docker.com/products/docker-desktop). On Apple Silicon (M1/M2/M3) it runs native arm64 — no flags needed. +- Make sure Docker Desktop is **running** (icon in menu bar) before you start anything below. **Windows:** -- Install WSL2 (`wsl --install` in PowerShell, then reboot). -- Install Docker Desktop and enable the WSL2 backend in Settings → General. -- Run **all commands below from inside the WSL2 Ubuntu shell**. +- Install [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) first (`wsl --install` in PowerShell, then reboot). +- Install Docker Desktop and enable the WSL2 backend in **Settings → General**. +- Run **all commands below from inside the WSL2 Ubuntu shell**, not PowerShell or CMD. +- Install Node + npm inside WSL2 (`sudo apt install nodejs npm` or use nvm inside WSL2). + +**Linux:** + +- Install Docker via your distro (`sudo apt install docker.io` on Ubuntu). +- Add yourself to the `docker` group so you don't need `sudo`: `sudo usermod -aG docker $USER`, then log out and back in. + +### What you do NOT need + +- A GitHub OAuth App +- A GitHub App +- A smee.io tunnel +- An Inngest, Groq, Sentry, or PostHog account +- A real Redis (in-memory fallback ships with the repo) + +For 95% of contributor work, you only need the steps below. --- -## 2. Local setup (Step-by-step) +## 2. Local setup (5 commands) -````bash -git clone [https://github.com/Coder-s-OG-s/MergeShip.git](https://github.com/Coder-s-OG-s/MergeShip.git) +```bash +git clone https://github.com/Coder-s-OG-s/MergeShip.git cd MergeShip -pnpm install +npm install cp .env.example .env.local +``` -Then start the local Supabase stack. First run pulls ~2.5GB of Docker images and takes 5-10 minutes. +Then start the local Supabase stack. **First run pulls ~2.5GB of Docker images and takes 5-10 minutes.** Subsequent starts are ~30 seconds. + +```bash make supabase-start +``` + +When it finishes, it prints URLs and keys. You need two keys from the output (or run `npx supabase status -o env` to print them again): -Apply migrations + seed dev personas: +- `ANON_KEY` → paste into `.env.local` as `NEXT_PUBLIC_SUPABASE_ANON_KEY` +- `SERVICE_ROLE_KEY` → paste into `.env.local` as `SUPABASE_SERVICE_ROLE_KEY` + +Then apply migrations + seed dev personas: + +```bash make db-reset +``` Start the dev server: -pnpm dev -App is live at http://localhost:3001. +```bash +npm run dev +``` -Koi baat nahi Yukti, hota hai! Panic mein aksar Cmd + A aur Delete dab hi jata hai. 😂 +App is live at **http://localhost:3001**. -Main niche poora final code wapas de raha hoon. Is baar ekdum dhyan se copy karna (code block ke top-right corner mein Copy icon use karna) aur use apni CONTRIBUTING.md mein paste karke save kar do. +--- -Markdown -# Contributing to MergeShip +## 3. Sign in -Welcome. This guide gets you from `git clone` to a running local app, then walks you through opening your first PR. Should take 15-20 minutes the first time. +Open **http://localhost:3001/dev/login** and click any of the six seeded personas: -Works the same on **macOS**, **Linux**, and **Windows (WSL2)**. Native Windows isn't supported — Supabase CLI has known issues outside WSL2. +| Persona | Level | What they have | +| ------- | ---------- | ----------------------------------------- | +| Alice | L0 | Brand new account, no audit yet | +| Bob | L1 | Audited, has active recommendations | +| Carol | L2 | 3 merges, mentor-eligible | +| Dave | L3 | Mentor with 5 mentees, sees `/maintainer` | +| Eve | L4 | Senior mentor, sees `/maintainer` | +| Frank | Maintainer | Owns demo/sample-repo, sees `/maintainer` | + +Click a button → instant sign-in via Supabase email/password (no real OAuth needed). The `/dev/login` page returns 404 in production builds. --- -## 1. Prerequisites +## 4. Daily commands -Install these once before starting: +```bash +make supabase-start # start local Postgres/Auth (idempotent) +npm run dev # dev server on :3001 with hot reload +make supabase-stop # shut down containers when done -| Tool | Version | Notes | -| --- | --- | --- | -| Node.js | 20 LTS or newer | Use nvm or nodejs.org. Verify: `node -v` | -| pnpm | latest | Package manager required for this project. Install via `npm install -g pnpm` | -| Docker | latest | Docker Desktop on macOS/Windows, `docker.io` on Linux | -| Supabase CLI | latest | Used for local database and auth testing | -| Git | any modern | Verify: `git --version` | +make db-reset # nuke + re-apply migrations + reseed personas +make test # run all tests +make test-watch # TDD mode +make typecheck # tsc --noEmit +make lint # eslint +make format # prettier --write +``` -### Platform-specific setup +--- -**macOS:** -- Install Docker Desktop. On Apple Silicon (M1/M2/M3) it runs native arm64. -- Make sure Docker Desktop is **running** before you start. +## 5. Repo layout + +``` +src/ + app/ + (app)/ # authenticated routes (dashboard, leaderboard, maintainer) + [handle]/ # public profile pages /@username + api/ # auth callback, github webhook, inngest endpoint + actions/ # server actions, one file per domain + dev/login/ # dev-only persona switcher + lib/ + cache/ # redis or in-memory fallback + db/ # drizzle schema + client + github/ # octokit factories, webhook hmac + help/ # help-routing logic + llm/ # groq router + maintainer/ # PR queue, issue triage, mentor flow + pipeline/ # difficulty scoring, rec ranking + supabase/ # supabase clients (browser / server / service-role) + xp/ # curve, events, caps, audit, sources, streak + inngest/ + client.ts + functions/ # background jobs +supabase/ + migrations/ # numbered SQL migrations +scripts/ + seed.ts # synthetic personas + sim-webhook.ts # fire mock webhook +``` + +Most contributor PRs only touch `src/app/`, `src/lib/`, or `src/app/actions/`. -**Windows:** -- Install WSL2 (`wsl --install` in PowerShell, then reboot). -- Install Docker Desktop and enable the WSL2 backend in Settings → General. -- Run **all commands below from inside the WSL2 Ubuntu shell**. +--- + +## 6. Picking what to work on + +1. Browse [issues labeled `good-first-issue`](https://github.com/Coder-s-OG-s/MergeShip/issues?q=is%3Aissue+is%3Aopen+label%3Agood-first-issue) or `gssoc`. +2. Comment "I'd like to work on this" before starting. +3. Wait for an assignment to avoid duplicate work. --- -## 2. Local setup (Step-by-step) +## 7. PR workflow ```bash -git clone [https://github.com/Coder-s-OG-s/MergeShip.git](https://github.com/Coder-s-OG-s/MergeShip.git) -cd MergeShip -pnpm install -cp .env.example .env.local -Then start the local Supabase stack. First run pulls ~2.5GB of Docker images and takes 5-10 minutes. +# 1. Sync main +git checkout main +git pull origin main -Bash -make supabase-start -Apply migrations + seed dev personas: +# 2. Branch +git checkout -b feat/short-name # also: fix/, chore/, docs/, refactor/ -Bash -make db-reset -Start the dev server: +# 3. Make changes + tests, then verify +make test +make typecheck +make lint -Bash -pnpm dev -App is live at http://localhost:3001. +# 4. Commit (one logical change per commit) +git add # not `git add .` +git commit # pre-commit hook runs prettier + eslint -3. Environment Variables Explanation (.env.example) -Your .env.local file requires specific keys to function properly. Here is what each variable does and where to get it: +# 5. Push + open PR +git push -u origin feat/short-name +``` -NEXT_PUBLIC_SUPABASE_ANON_KEY: Public key for Supabase client. You get this from the terminal output after running make supabase-start or by running npx supabase status -o env. +Open the PR via the GitHub web UI or `gh pr create`. -SUPABASE_SERVICE_ROLE_KEY: Admin key for server-side Supabase operations. Found in the same terminal output mentioned above. +PR title follows [conventional commits](https://www.conventionalcommits.org/): `feat(scope): ...`, `fix(scope): ...`, `chore: ...`, `test: ...`, `docs: ...`, `refactor: ...`. -GITHUB_APP_ID, GITHUB_APP_CLIENT_ID, GITHUB_APP_CLIENT_SECRET, GITHUB_APP_PRIVATE_KEY: Required for GitHub webhook integration. You generate these by creating a GitHub App in your developer settings (See Section 12). +PR body must include: what changed, why, test plan, and `Closes #N`. -GITHUB_WEBHOOK_SECRET: A custom random string you set when configuring your GitHub App webhooks. +--- -4. Sign in -Open http://localhost:3001/dev/login and click any seeded persona (Alice, Bob, etc.) for instant sign-in. The /dev/login page returns 404 in production builds. +## 8. By the type of change you're making -5. Daily commands +### A. UI tweak / new page -make supabase-start # start local Postgres/Auth -pnpm dev # dev server on :3001 with hot reload -make supabase-stop # shut down containers +1. Find or create the file under `src/app/(app)/` or `src/components/`. +2. Edit and watch it hot-reload at localhost:3001. +3. Test with different personas via `/dev/login` to cover L0/L1/L2/maintainer states. +4. Tests not strictly required for UI but encouraged for logic. -make db-reset # nuke + re-apply migrations + reseed personas -make test # run all tests -make typecheck # tsc --noEmit -make lint # eslint -make format # prettier --write +### B. New server action -6. PR workflow & Guidelines +1. Add it to an existing `src/app/actions/.ts` or create a new file. +2. First line of the file: `'use server'`. +3. Auth-check at top: `const { data: { user } } = await sb.auth.getUser(); if (!user) return err(...)`. +4. Wrap with `rateLimit({ namespace: '...', key: user.id, limit, windowSec })`. +5. Return a `Result` envelope: `ok(data)` or `err(code, message)`. +6. **Tests required.** Mock supabase, assert the result shape. -# 1. Sync main -git checkout main -git pull origin main +### C. Pure helper in `lib/` -# 2. Branch naming conventions -# Use descriptive prefixes: fix/issue-name or feat/feature-name -git checkout -b feat/short-name +1. Create `src/lib//your-thing.ts` and a `.test.ts` alongside it. +2. **TDD**: write the failing test first. +3. Keep it pure — no I/O, no DB, no fetch. +4. Coverage gate: `lib/` must stay ≥80%. -# 3. Verify changes -make test -make typecheck -make lint +### D. New XP rule -# 4. Commit format -# Use conventional commits: fix: description or feat: description -git add -git commit +1. Add to `XP_REWARDS` and `XP_SOURCE` in `src/lib/xp/sources.ts`. +2. Add `refIds.yourThing(...)` so the idempotency key is unique. +3. Add a cap in `src/lib/xp/caps.ts` if it's user-actionable. +4. Fire the event from where the action happens. +5. Tests required for cap + idempotency. -# 5. Push + open PR -git push -u origin feat/short-name +### E. New Inngest function -PR title must follow conventional commits. PR body must include: what changed, why, and Closes #N. +1. Create `src/inngest/functions/your-function.ts`. +2. Wrap durable work in `step.run('name', async () => ...)`. +3. Use `concurrency: { key: 'event.data.', limit: 1 }` to prevent races. +4. Register in `src/app/api/inngest/route.ts`. +5. To run locally, start the Inngest dev server in another terminal: + ```bash + npx inngest-cli@latest dev + ``` + Functions auto-register from `/api/inngest`. UI at http://localhost:8288. -7. Code style — non-negotiable -Tailwind Only: Strictly use Tailwind classes for styling. No custom CSS. +### F. DB migration -No emojis: Do not use emojis in the codebase or commit messages. +1. Create `supabase/migrations/000N_short_name.sql` (N = next number). +2. Use `if not exists` / `if exists` for safe reruns. +3. Mirror the columns/tables in `src/lib/db/schema.ts`. +4. RLS: every new table needs `enable row level security` + an explicit policy. +5. Run `make db-reset` to verify it applies cleanly. -Minimal comments: Write self-documenting code. No comments unless absolutely necessary for complex logic. +### G. Webhook handler change -No any — use unknown + narrowing. +1. Edit the relevant file in `src/inngest/functions/process-*.ts`. +2. Test locally — see the next section. -No console.log in committed code. +### H. Bug fix -File names: kebab-case.ts. Variables: camelCase. Types: PascalCase. SQL: snake_case. +1. Reproduce locally first. +2. Write a failing test that captures the bug. +3. Fix the code, watch the test go green. +--- -8. By the type of change you're making -A. UI tweak / new page -Find or create the file under src/app/(app)/ or src/components/. Test with different personas via /dev/login. +## 9. Testing webhook handlers -B. New server action -First line: 'use server'. Return a Result envelope. Tests required. +You do **not** need a real GitHub App. The repo includes a webhook simulator that signs and POSTs synthetic payloads: -C. Pure helper in lib/ -Keep it pure — no I/O, no DB, no fetch. Coverage gate: lib/ must stay ≥80%. +```bash +npm run sim:webhook -- pr-merged --handle bob --repo demo/sample-repo --pr 123 +npm run sim:webhook -- review --handle dave --pr-url https://github.com/demo/sample-repo/pull/123 +npm run sim:webhook -- install --handle alice +``` -D. DB migration -Create supabase/migrations/000N_short_name.sql. Run make db-reset to verify. +The `--` is required to pass flags through npm. -9. Testing webhook handlers -The repo includes a webhook simulator that signs and POSTs synthetic payloads: +Two outcomes: -npm run sim:webhook -- pr-merged --handle bob --repo demo/sample-repo --pr 123 +- **Inngest dev server running** (`npx inngest-cli@latest dev`) → the function runs, you can verify DB state changed. +- **No Inngest dev server** → returns 202 with a log message. The webhook delivery row is still inserted; this is the right behavior for testing the route itself. + +--- + +## 10. Code style — non-negotiable + +- No `any` — use `unknown` + narrowing. +- No `console.log` in committed code. +- No emojis in code unless the user explicitly asked. +- Comments explain WHY, not WHAT. +- No `--no-verify` on commits — fix the lint issue instead. +- One PR = one logical change. +- File names: `kebab-case.ts`. Variables: `camelCase`. Types: `PascalCase`. SQL: `snake_case`. + +The pre-commit hook runs prettier + eslint. If it blocks your commit, fix the issue and re-commit — never bypass. + +--- + +## 11. Tests — required when + +| Touching | Tests required? | +| ------------------------ | --------------------------- | +| `src/lib/**` | Yes | +| `src/app/actions/**` | Yes | +| `src/inngest/**` | Yes | +| `supabase/migrations/**` | Yes (RLS or trigger tests) | +| `src/app/**` UI | Encouraged, reviewer's call | + +Coverage gate: `lib/` ≥ 80% lines. CI blocks merge if it drops. + +--- -10. Tests — required when +## 12. Troubleshooting -Touching,Tests required? -src/lib/**,Yes -src/app/actions/**,Yes -src/inngest/**,Yes -supabase/migrations/**,Yes (RLS or trigger tests) +**`supabase: command not found`** +Run via `make supabase-start` or `npx supabase ...`. Don't install supabase globally. -11. Troubleshooting -supabase: command not found: Run via make supabase-start. +**`Cannot connect to the Docker daemon`** +Docker Desktop isn't running. Start it. On Linux: `sudo systemctl start docker`. -Cannot connect to the Docker daemon: Start Docker Desktop. +**`supabase start` hangs** +First run pulls ~2.5GB of images. Wait 5-10 min. Stuck after 15 min: `Ctrl-C`, run `npx supabase stop`, then retry. -Port already in use: Kill the process using port 3001 or 54321. +**Supabase containers crash / out of memory** +Docker Desktop → Settings → Resources → bump Memory to at least 4GB. -/dev/login returns 404: Ensure you are using pnpm dev. +**Port 54321 / 54322 / 54323 / 3001 already in use** +Another instance running. To free a port: -12. GitHub App setup instructions (Webhook integration) -If you need to test actual webhook delivery: +- macOS/Linux: `lsof -ti:3001 | xargs kill` +- Windows (WSL2): `lsof -ti:3001 | xargs -r kill` -Go to GitHub Developer Settings -> GitHub Apps -> New GitHub App. +Another supabase project running? `npx supabase stop` from its directory. -Homepage URL: http://localhost:3001 +**`SUPABASE_SERVICE_ROLE_KEY required` when running seed** +You haven't pasted the `service_role` key into `.env.local`. Run `npx supabase status -o env` and copy `SERVICE_ROLE_KEY`'s value into `SUPABASE_SERVICE_ROLE_KEY=...` in `.env.local`. -Webhook URL: Use a tunneling service like smee.io. +**`/dev/login` returns 404** +You're in production mode. Use `npm run dev`, not `npm run build && npm start`. -Webhook secret: Create a random string. +**Persona button shows "Invalid credentials"** +The seed didn't run. `make db-seed`. -Generate and download the private key (.pem). +**"relation X already exists" on migration** +`make db-reset` wipes and reapplies cleanly. + +**Tests fail with "fetch failed" to Supabase** +Local Supabase isn't running. `make supabase-start`. + +**Prettier fails in CI but passes locally** +Run `make format` then commit. Usually a markdown file picked up formatter drift. + +**`npm install` peer dependency errors** +Only use npm (not pnpm/yarn). `rm -rf node_modules package-lock.json && npm install`. + +**`Cannot find module '@/lib/...'`** +VS Code: `Cmd/Ctrl+Shift+P` → "TypeScript: Select Version" → "Use Workspace Version". + +**Hot reload not working** +Restart `npm run dev`. Usually a circular import. + +**Cookie / session issues** +Use `http://localhost:3001`, not `127.0.0.1:3001`. Auth cookies are hostname-scoped. + +**Windows: CRLF line ending warnings** + +```bash +git config --global core.autocrlf input +``` + +**TypeScript error in a file you didn't touch** +Someone else's PR landed something that conflicts with your branch. Pull main and rebase. + +--- + +## 13. Advanced — testing with a real GitHub App + +Skip unless you need to debug actual webhook delivery from GitHub. Almost no PRs need this. + +1. https://github.com/settings/apps/new +2. Name: globally unique (e.g. `mergeship-dev-yourname`) +3. Homepage URL: `http://localhost:3001` +4. Webhook URL: a smee.io channel (generate at smee.io) +5. Webhook secret: a random string, save it +6. Permissions: Pull requests R+W, Issues R+W, Metadata R, Pull request review R +7. Subscribe: Pull request, Pull request review, Issues, Issue comment, Installation, Installation repositories +8. Generate + download private key (`.pem`) +9. Install on a test repo you own +10. Fill `.env.local`: + ``` + GITHUB_APP_ID= + GITHUB_APP_CLIENT_ID= + GITHUB_APP_CLIENT_SECRET= + GITHUB_APP_PRIVATE_KEY="" + GITHUB_WEBHOOK_SECRET= + MOCK_GITHUB_API=false + MOCK_GITHUB_WEBHOOKS=false + ``` +11. Terminal A: `npx smee-client --url https://smee.io/ --target http://localhost:3001/api/webhooks/github` +12. Terminal B: `npx inngest-cli@latest dev` +13. Trigger events on your test repo, watch them flow + +--- + +## 14. Security + +- Never commit `.env.local`, `.env`, `*.pem`, or any file with secrets. +- Never paste service role keys in issues or PRs. +- Never `git add .` blindly — stage specific files. +- Never bypass pre-commit hooks. + +--- + +## 15. Getting help + +1. Re-read the [Troubleshooting](#12-troubleshooting) section. +2. Search closed issues + PRs for your error. +3. Open a [GitHub Discussion](https://github.com/Coder-s-OG-s/MergeShip/discussions) with the `help-wanted` label. +4. GSSoC contributors: drop in the cohort Discord channel. +5. Tag the maintainer only after the above. + +Include in any help request: + +- OS + Node version (`node -v`) +- Exact command that failed +- Full error text (paste it, not a screenshot) +- What you already tried + +--- -Update .env.local with the generated App ID, Client ID, Client Secret, Webhook Secret, and the exact contents of the PEM file. +## 16. License +By opening a PR you agree to license your contribution under the project's [MIT License](LICENSE). You retain copyright on your contribution. -```` +We don't add AI-attribution footers to commits — author your work yourself. From 426aeeb91e6683499102e11705b5fde8713e38b4 Mon Sep 17 00:00:00 2001 From: Yukti Nandwana Date: Sat, 16 May 2026 16:23:54 +0530 Subject: [PATCH 5/5] docs: add discussions link and restore claim limit --- CONTRIBUTING.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5d96b8f..1ffb573 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,11 +3,10 @@ Welcome. This guide gets you from `git clone` to a running local app, then walks you through opening your first PR. Should take 15-20 minutes the first time. Works the same on **macOS**, **Linux**, and **Windows (WSL2)**. Native Windows isn't supported — Supabase CLI has known issues outside WSL2. +**Got a question before you start? Join the conversation on [GitHub Discussions](https://github.com/Coder-s-OG-s/MergeShip/discussions) - introductions, setup help, feature ideas, anything.** --- -**Got a question before you start? Join the conversation on [GitHub Discussions](https://github.com/Coder-s-OG-s/MergeShip/discussions) - introductions, setup help, feature ideas, anything.** - ## 1. Prerequisites Install these once: @@ -160,6 +159,9 @@ Most contributor PRs only touch `src/app/`, `src/lib/`, or `src/app/actions/`. 2. Comment "I'd like to work on this" before starting. 3. Wait for an assignment to avoid duplicate work. +**Claim limit: maximum 3 issues at a time.** +If you already have 3 open issues assigned or 3 open PRs, you must get them merged or closed before picking up anything new. A bot will automatically unassign you and leave a comment if you go over the limit. This keeps issues available for others and prevents hoarding. + --- ## 7. PR workflow