Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
112 lines (74 loc) · 4.05 KB

CONTRIBUTING.md

File metadata and controls

112 lines (74 loc) · 4.05 KB
Raw

Contributing to RepoGraph

Thanks for having a look. This is a side project turned open source, maintained under RepoGraphs. Any help is appreciated, whether that's a bug fix, docs tweak, or a new relationship rule.

By contributing you agree your work on the core (apps/, packages/) falls under AGPL-3.0. See CLA.md.

Getting set up

You need Node 20+, pnpm 9+, and ideally Docker. You'll also want a GitHub token (read-only is fine) or most things will just return empty.

# fork the repo on GitHub first, then:
git clone https://github.com/<your-username>/repograph.git
cd repograph
git remote add upstream https://github.com/RepoGraphs/repograph.git

cp .env.example .env
# set GITHUB_TOKEN in .env

docker compose up -d postgres redis

pnpm install
pnpm db:generate && pnpm db:migrate
pnpm dev

Web runs on http://localhost:3000, API on http://localhost:3001.

Before you push anything, run:

pnpm lint && pnpm typecheck && pnpm test

If that passes, you're in good shape. CI runs the same thing.

How I like PRs to look

  • One thing per PR. A bug fix, one new rule, one component. Easier to review, faster to merge.
  • Branch off main: feat/something, fix/something, docs/something.
  • Link the issue if there is one. Screenshots for anything visual.
  • I try to review within a couple of days. Small PRs usually go first.

Good starting points are issues tagged good first issue.

Where things live

  • apps/web — Next.js frontend
  • apps/api — NestJS backend
  • packages/graph-model — just types, keep it that way, no runtime deps
  • packages/github-client — GitHub fetching, don't import the relationship engine from here
  • packages/relationship-engine — one file per relationship in rules/
  • packages/db — Prisma schema and migrations
  • packages/ui — shared bits, use the tokens in packages/config, don't hardcode colors

Longer version of the boundaries is in ARCHITECTURE.md.

A few rules

  • TypeScript strict. Avoid any in new code unless you have a good reason.
  • Run prettier/eslint before pushing. Config lives in packages/config.
  • Don't hardcode stars, counts, or any metrics in app code. Live data comes from GitHub. The demo list in apps/web/lib/mock.ts is links only, and the seed in packages/db/prisma/seed.ts is dev-only sample data. Keep it that way.
  • Graph queries always need a focus, depth 1-2, limit max 400. If you touch that logic, keep the 400s helpful.

Adding a relationship

This is the most common change. It's deliberately boring:

  1. Add your type in packages/graph-model/src/types.ts
  2. Create packages/relationship-engine/src/rules/my_relation.ts that returns edges with evidence[] and a sourceUrl each. No evidence, no merge.
  3. Register it in packages/relationship-engine/src/rules/index.ts
  4. Add my_relation.test.ts next to it

Look at an existing rule first and copy the shape.

Adding UI

Put shared stuff in packages/ui/src/. Use the existing tokens, check dark mode, and glance at it on mobile width. Drop a screenshot in the PR.

Commits

I use conventional commits, nothing strict, just keep it readable:

feat: add review_requested edge
fix: retry on 429 with backoff
docs: fix docker command in readme

Checklist I run through on review:

  • lint + typecheck + tests pass
  • no .env or tokens slipped in
  • no fake numbers or lorem ipsum in user-facing code
  • tests added if behavior changed
  • docs updated if needed

Stuff you shouldn't change without talking first

  • GET /repositories/:id/graph needing focus, depth/limit caps
  • edge.confidence being only explicit or derived
  • cache key shapes and TTLs in ARCHITECTURE.md

Open an issue with the rfc idea first and we'll figure it out.

Security

Don't log tokens, don't send them to the browser, validate the repo URL on resolve. If you spot a real vulnerability, email security@repograph.dev instead of opening an issue. Details in SECURITY.md.

Questions

Just open an issue with the question label. That's the fastest way to reach me.