Skip to content

Commit ecefd95

Browse files
devakonedevakone
committed
docs(contributing): add contributor orientation guide
1 parent 64a957f commit ecefd95

3 files changed

Lines changed: 162 additions & 0 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ Thanks for helping improve Vibe Coding Profiler! We welcome new contributors—h
77
- **Bug/issue:** Open an issue describing the behaviour, steps to reproduce, and expected outcome.
88
- **New feature:** Link to the relevant PRD or tracker under `docs/prd/` and coordinate in `docs/implementation-trackers/`.
99
- **Docs or security improvements:** Target the `docs/` tree (architecture, security readiness, workflow notes).
10+
- **Need orientation first:** Read `docs/contributor-orientation.md` for a practical map of where to make changes.
1011

1112
Before working, confirm nobody else is already tackling it (add a comment or label the issue). If you’re unsure, open a discussion issue and tag `@devakone`.
1213

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ Vibe Coding Profiler is an open-source “Vibe Coding Profile” experience that
2727

2828
## Documentation
2929

30+
- `docs/contributor-orientation.md`: onboarding map for new contributors (where to edit, how to validate, release flow)
3031
- `docs/security/open-source-preparedness.md`: release readiness + remaining hardening steps
3132
- `docs/PRD.md`: product requirements driving the interface
3233
- `docs/architecture/`: pipeline, LLM, share experiences

‎docs/contributor-orientation.md‎

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
# Contributor Orientation Guide
2+
3+
This guide helps new contributors understand where to look in the codebase, how the app works end-to-end, and how to make safe first contributions.
4+
5+
Use this alongside:
6+
- `README.md` for quick setup
7+
- `CONTRIBUTING.md` for contribution policy
8+
- `docs/architecture/overview.md` for system-level architecture
9+
- `docs/architecture/vibed-analysis-pipeline.md` for analysis internals
10+
11+
## 1. What This Repo Does
12+
13+
Vibe Coding Profiler analyzes git history and produces:
14+
- repo-level analysis (metrics, insights, persona signals)
15+
- user profile aggregation over time
16+
- shareable outputs (public profile + share cards)
17+
18+
Core flow:
19+
1. User connects source control and repos in the web app.
20+
2. API creates `analysis_jobs`.
21+
3. Inngest (primary) or worker (fallback) processes jobs.
22+
4. Results are written to Supabase tables.
23+
5. UI renders analysis and profile views from stored results.
24+
25+
## 2. Monorepo Layout
26+
27+
Top-level packages:
28+
- `apps/web`: Next.js app (UI + API routes + Inngest functions)
29+
- `apps/worker`: standalone fallback worker
30+
- `packages/core`: shared analysis logic and persona computation
31+
- `packages/db`: DB client helpers + generated database types
32+
- `supabase/migrations`: schema and RLS migrations
33+
- `docs`: product, architecture, trackers, security notes
34+
35+
## 3. Where To Make Changes
36+
37+
Use this map to find the right place quickly.
38+
39+
### UI and page behavior
40+
- Pages/routes: `apps/web/src/app`
41+
- Shared UI: `apps/web/src/components/ui`
42+
- VCP-specific components: `apps/web/src/components/vcp`
43+
- Share visuals: `apps/web/src/components/share`
44+
45+
### API behavior (web backend)
46+
- API routes: `apps/web/src/app/api`
47+
- Auth/provider integration: `apps/web/src/app/api/auth`, `apps/web/src/lib/platforms`
48+
- Profile/public endpoints: `apps/web/src/app/api/profile`, `apps/web/src/app/api/public`
49+
50+
### Analysis logic and personas
51+
- Metrics, persona detection, insights: `packages/core/src`
52+
- Platform clients abstraction: `packages/core/src/platforms`
53+
- LLM helper logic: `packages/core/src/llm`
54+
55+
### Job orchestration
56+
- Primary processing: `apps/web/src/inngest/functions`
57+
- Fallback processing: `apps/worker/src`
58+
59+
### Database schema and policies
60+
- Migrations: `supabase/migrations`
61+
- Seed and local setup: `supabase/seed.sql`, `scripts/supabase.mjs`
62+
63+
## 4. Local Development Loop
64+
65+
From repo root:
66+
67+
1. Install dependencies:
68+
```bash
69+
npm install
70+
```
71+
72+
2. Configure environment:
73+
```bash
74+
cp .env.example apps/web/.env.local
75+
```
76+
77+
3. Start local Supabase:
78+
```bash
79+
npm run supabase:start
80+
```
81+
82+
4. Start web app:
83+
```bash
84+
npm run dev:web
85+
```
86+
87+
5. Run quality checks before PR:
88+
```bash
89+
npm run lint
90+
npm run type-check
91+
npm run build
92+
```
93+
94+
Notes:
95+
- Web default port is `8108`.
96+
- Prefer `npm run supabase:*` scripts (not raw `npx supabase`) so env loading is consistent.
97+
98+
## 5. Safe First Contributions
99+
100+
Good first PRs:
101+
- docs clarifications and dead-link fixes
102+
- UI copy polish in existing pages/components
103+
- small bug fixes in API routes with tests
104+
- type improvements in `packages/core`
105+
106+
Higher-risk changes (coordinate first):
107+
- migrations touching auth/RLS
108+
- changes to job claim/processing flow
109+
- provider token/encryption handling
110+
- broad refactors across `apps/web` + `packages/core`
111+
112+
## 6. How To Validate a Change
113+
114+
### Frontend/UI changes
115+
- Verify page renders and navigation paths.
116+
- Check authenticated and unauthenticated flows.
117+
- Ensure no metadata/route warnings in dev/build logs.
118+
119+
### API/backend changes
120+
- Test route manually with valid and invalid inputs.
121+
- Confirm error responses are structured and safe.
122+
- Re-run `npm run type-check` and `npm run build`.
123+
124+
### Analysis logic changes
125+
- Update/add tests under `packages/core/src/__tests__`.
126+
- Verify output shape compatibility with web consumers.
127+
- Validate no regressions in existing persona/metrics tests.
128+
129+
### DB changes
130+
- Create new migration only (never edit applied migration files).
131+
- Apply with `npm run supabase:migration:up`.
132+
- Confirm RLS expectations before merge.
133+
134+
## 7. How Releases Flow
135+
136+
- `develop` is active integration branch.
137+
- `main` is release branch.
138+
- Release PR sync workflow keeps a `develop -> main` PR updated.
139+
- Release notes body is generated automatically from commit history.
140+
141+
If release PR automation fails, check:
142+
- `.github/workflows/release-pr.yml`
143+
- repo Actions permissions
144+
- `RELEASE_PR_TOKEN` secret scope
145+
146+
## 8. Contributor Checklist
147+
148+
Before opening a PR:
149+
1. Keep your branch scoped to one concern.
150+
2. Run lint, type-check, and build locally.
151+
3. Update docs if behavior, setup, or architecture changed.
152+
4. Ensure no secrets are introduced.
153+
5. Use clear commit messages (conventional format preferred).
154+
155+
## 9. Security and OSS Expectations
156+
157+
- Never commit `.env` files or tokens.
158+
- Run local secret scans when touching auth/secrets code.
159+
- Follow `SECURITY.md` reporting process for vulnerabilities.
160+
- Respect trademark policy in `README.md` and `CONTRIBUTING.md`.

0 commit comments

Comments
 (0)