Skip to content

Commit 4b84af2

Browse files
kelvinator07kelvinator07
authored
Merge pull request #4 from btrustteam/docs/update-readme
docs: update README with setup, features, and env vars
2 parents af64c3c + 2e89454 commit 4b84af2

2 files changed

Lines changed: 107 additions & 52 deletions

File tree

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025 Btrust
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 86 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -1,52 +1,86 @@
1-
## Github Developer Review
2-
3-
## Build Phases
4-
5-
### Phase 1 -- Foundation (Auth + API + Data Layer)
6-
7-
- Next.js project scaffold with TypeScript, Tailwind, shadcn/ui
8-
- GitHub OAuth App setup + Auth.js integration
9-
- Login page with "Sign in with GitHub" button
10-
- Protected route middleware (redirect to login if unauthenticated)
11-
- API route for GraphQL overview (`/api/github/overview/[username]`) using reviewer's OAuth token
12-
- Bitcoin repo classifier with tiered relevance (`lib/bitcoin-repos.ts` + `config/bitcoin-repos.json`)
13-
- Server-side cache with Vercel KV (`lib/cache.ts`)
14-
- Rate-limited fetch helper with per-token tracking and retry/queue logic (`lib/github-search.ts`)
15-
- Core types in `lib/types.ts`
16-
- Skeleton components (`Skeletons.tsx`) and error banners (`ErrorBanner.tsx`) -- built from the start, not bolted on later
17-
18-
### Phase 2 -- Search + Overview UI
19-
20-
- Search page with recent searches
21-
- Overview dashboard with skeleton loading states for every section:
22-
- Profile card (loads first, single call)
23-
- Stats grid (7 cards including commits, merge rate, avg lines changed)
24-
- Contribution heatmap
25-
- Contribution timeline chart (recharts line chart, monthly aggregation)
26-
- Top projects with tier badges
27-
- SWR data fetching hooks
28-
- Error banners for rate limit / partial results / API failures
29-
30-
### Phase 3 -- Drill-Down + Filtering
31-
32-
- API routes for PRs, reviews, comments (REST Search)
33-
- Drill-down page with tabbed interface (lazy-loaded tabs)
34-
- ContributionTable with clickable GitHub links + skeleton loading per tab
35-
- Expandable rows with quality signals (lines changed, commits, time-to-merge) -- lazily fetched via `github-pr-detail.ts`
36-
- Date filter bar with quick presets
37-
- Project, status, and tier filters
38-
- "Load more" pagination
39-
- Mobile card layout (`ContributionCard.tsx`) for screens < 768px
40-
41-
### Phase 4 -- Polish + Responsive
42-
43-
- Mobile bottom-sheet for filter bar
44-
- Horizontal scroll for heatmap + tabs on small screens
45-
- Responsive stats grid (3x2 -> 2x3 -> 1x6)
46-
- Rate limit badge in header (per reviewer)
47-
- Empty states ("No bitcoin contributions found")
48-
- "Show adjacent projects" toggle on overview
49-
- End-to-end testing of rate limit recovery (partial results, retry, queue)
50-
- URL deep linking for drill-down filters
51-
- Unit tests for Bitcoin repo classifier
52-
- Accessibility: aria labels on heatmap, keyboard navigation, colorblind-safe badges
1+
# GitHub Developer Review
2+
3+
Evaluate Bitcoin open-source contributors for grant funding. Sign in with GitHub, search by username, and view contribution stats, heatmaps, project breakdowns, and filterable PRs, reviews, and issues.
4+
5+
## Features
6+
7+
- **GitHub OAuth** — Sign in with GitHub to access the dashboard and developer views.
8+
- **Developer overview** — Profile card, contribution stats, yearly heatmap, and monthly timeline.
9+
- **Bitcoin projects** — Repos classified as core, ecosystem, or adjacent; top projects with contribution counts and a “Load more” list.
10+
- **Contributions drill-down** — Tabs for Pull Requests, Reviews, and Issues; filters by date, project, status, and tier; table (desktop) and cards (mobile) with “Load more” pagination.
11+
- **Recent searches** — Persisted in `localStorage` for quick re-visits from the dashboard.
12+
- **Rate limit awareness** — UI shows GitHub API rate limit status and retry guidance when applicable.
13+
14+
## Tech stack
15+
16+
- **Next.js 16** (App Router), **React 19**
17+
- **NextAuth v5** (GitHub provider)
18+
- **Tailwind CSS v4**, **shadcn/ui**
19+
- **SWR** for data fetching; **Vercel KV** for server-side caching (optional)
20+
- **Vitest** + **Testing Library** for tests
21+
22+
## Prerequisites
23+
24+
- Node.js 20+
25+
- A [GitHub OAuth App](https://github.com/settings/developers) (Client ID and Client Secret)
26+
27+
For caching (recommended in production):
28+
29+
- [Vercel KV](https://vercel.com/docs/storage/vercel-kv) or a Redis-compatible store with the same env vars.
30+
31+
## Environment variables
32+
33+
Create a `.env.local` in the project root:
34+
35+
| Variable | Required | Description |
36+
|----------|----------|-------------|
37+
| `AUTH_SECRET` | Yes | Secret for NextAuth session encryption (e.g. `openssl rand -base64 32`) |
38+
| `AUTH_GITHUB_ID` | Yes | GitHub OAuth App Client ID |
39+
| `AUTH_GITHUB_SECRET` | Yes | GitHub OAuth App Client Secret |
40+
| `KV_REST_API_URL` | No | Vercel KV REST API URL (for server-side cache) |
41+
| `KV_REST_API_TOKEN` | No | Vercel KV REST API token |
42+
43+
Without KV vars, the app still runs; cache reads/writes will fail and the app will fall back to uncached GitHub API calls.
44+
45+
## Getting started
46+
47+
```bash
48+
# Install dependencies
49+
npm install
50+
51+
# Run development server
52+
npm run dev
53+
```
54+
55+
Open [http://localhost:3000](http://localhost:3000). Sign in with GitHub, then use the dashboard to search for a GitHub username and open their developer overview.
56+
57+
## Scripts
58+
59+
| Command | Description |
60+
|---------|-------------|
61+
| `npm run dev` | Start Next.js dev server |
62+
| `npm run build` | Production build |
63+
| `npm run start` | Run production server |
64+
| `npm run lint` | Run ESLint |
65+
| `npm run test` | Run Vitest in watch mode |
66+
| `npm run test:run` | Run Vitest once (e.g. in CI) |
67+
68+
## CI
69+
70+
The repo includes a GitHub Actions workflow (`.github/workflows/ci.yml`) that on pull requests to `main` runs:
71+
72+
- TypeScript check (`npx tsc --noEmit`)
73+
- Lint (`npm run lint`)
74+
- Build (`npm run build`)
75+
- Tests (`npx vitest run`)
76+
77+
## Project structure (high level)
78+
79+
- `src/app/` — App Router routes: login (`/`), `dashboard`, `developer/[username]`, and API routes under `api/`.
80+
- `src/components/` — UI: dashboard, developer overview, heatmap, timeline, top projects, contribution drill-down, shared UI and skeletons.
81+
- `src/hooks/` — Data and UI hooks (e.g. overview, contributions, recent searches, filters).
82+
- `src/lib/` — Auth, GitHub REST/GraphQL, cache, stats, types, and utilities.
83+
84+
## License
85+
86+
MIT. See [LICENSE](LICENSE).

0 commit comments

Comments
 (0)