Skip to content

Commit 4eaaeba

Browse files
HangzhiHangzhi
committed
Update contributors page: rank by PR count, simplify cards, add CSVs and enriched data
- Rank contributors by PR count instead of total additions - Simplify contributor cards to show only name and @handle (remove affiliation, stats) - Add is_adapter_contributor column to contributors.csv - Generate contributors_ready_to_show.csv with webpage-only fields - Enrich 22 contributors with names/affiliations from web research - Add IMPLEMENTATION.md documenting the full implementation plan
1 parent 983ad0c commit 4eaaeba

File tree

9 files changed

+3082
-2622
lines changed

9 files changed

+3082
-2622
lines changed

‎IMPLEMENTATION.md‎

Lines changed: 259 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,259 @@
1+
# Contributors Page — Implementation Plan
2+
3+
## Goal
4+
5+
Add a **Contributors** tab to the [Harbor Framework website](https://harborframework.com/) that displays all project contributors, organized into three sections: Harbor Contributors, Harbor Adapter Contributors, and Acknowledgments.
6+
7+
**Reference design**: [tbench.ai/contributors](https://www.tbench.ai/contributors)
8+
9+
---
10+
11+
## 1. Data Collection Pipeline
12+
13+
All scripts live at the repo root (`~/terminal-bench-harbor-translate/harbor-docs/`). They use the `gh` CLI to query the GitHub API and output JSON files consumed by the Next.js page.
14+
15+
### 1.1 Collect Merged PR Data — `collect_pr_data.py`
16+
17+
**Input**: GitHub API (`laude-institute/harbor` repo)
18+
**Output**: `raw_pr_data.json`
19+
20+
| Field | Description |
21+
|-------|-------------|
22+
| `pr_number` | Pull request number |
23+
| `pr_url` | URL to the PR on GitHub |
24+
| `author_github_handle` | GitHub username of the PR author |
25+
| `additions` | Lines added |
26+
| `deletions` | Lines deleted |
27+
| `pr_title` | Title of the PR |
28+
| `pr_type` | One of: `adapter`, `task`, `engineering`, `other` |
29+
30+
**PR type classification logic** (applied in order):
31+
1. `adapter` — title or labels contain "adapter"
32+
2. `task` — title or labels contain "task"
33+
3. `engineering` — title or labels match CI/CD/infra/build/chore/refactor keywords
34+
4. `other` — everything else
35+
36+
**How to run**:
37+
```bash
38+
python collect_pr_data.py
39+
# Requires: gh CLI authenticated with repo access
40+
# Output: raw_pr_data.json (264 merged PRs)
41+
```
42+
43+
### 1.2 Collect PR Author Info — `collect_user_data.py`
44+
45+
**Input**: `raw_pr_data.json` (reads unique author handles)
46+
**Output**: `raw_github_users_data.json`
47+
48+
| Field | Description |
49+
|-------|-------------|
50+
| `github_handle` | GitHub username |
51+
| `email` | Public email (may be `null`) |
52+
| `name` | Display name (falls back to handle) |
53+
| `affiliation` | Company/organization from GitHub profile |
54+
55+
**How to run**:
56+
```bash
57+
python collect_user_data.py
58+
# Requires: raw_pr_data.json, gh CLI
59+
# Output: raw_github_users_data.json (95 unique authors)
60+
```
61+
62+
### 1.3 Generate Aggregated Contribution Data — `generate_contributions.py`
63+
64+
**Input**: `raw_pr_data.json` + `raw_github_users_data.json`
65+
**Output**: `harbor_contribution.json`, `public/harbor_contribution.json`, `contributors_ready_to_show.csv`, `contributors.csv`
66+
67+
**JSON output fields** (`harbor_contribution.json`):
68+
69+
| Field | Description |
70+
|-------|-------------|
71+
| `github_handle` | GitHub username (used as key) |
72+
| `email` | Public email |
73+
| `name` | Display name |
74+
| `affiliation` | Company/organization |
75+
| `pr_count` | Total number of merged PRs |
76+
| `total_additions` | Sum of all additions across PRs |
77+
| `total_deletions` | Sum of all deletions across PRs |
78+
| `pr_list` | Array of `{ pr_url, pr_title, pr_type }` |
79+
80+
**Ranking**: Contributors are sorted by `pr_count` (number of merged PRs) descending.
81+
82+
**CSV outputs**:
83+
84+
| File | Columns | Purpose |
85+
|------|---------|---------|
86+
| `contributors_ready_to_show.csv` | `github_handle`, `name`, `has_adapter_pr`, `has_non_adapter_pr` | Only the fields needed to render the webpage |
87+
| `contributors.csv` | `github_handler`, `name`, `affiliation`, `email` | Full contact/attribution info for all contributors |
88+
89+
The script also copies `harbor_contribution.json` to `public/harbor_contribution.json` so Next.js can statically import it at build time.
90+
91+
**How to run**:
92+
```bash
93+
python generate_contributions.py
94+
# Requires: raw_pr_data.json, raw_github_users_data.json
95+
# Output: harbor_contribution.json, public/harbor_contribution.json,
96+
# contributors_ready_to_show.csv, contributors.csv (95 contributors)
97+
```
98+
99+
### 1.4 Full Pipeline (run all three in sequence)
100+
101+
```bash
102+
python collect_pr_data.py && python collect_user_data.py && python generate_contributions.py
103+
```
104+
105+
---
106+
107+
## 2. Navigation Update
108+
109+
**File**: `src/lib/layout.shared.tsx`
110+
111+
Add a "Contributors" link as the third nav tab (between Registry and Discord):
112+
113+
```tsx
114+
links: [
115+
{ url: "/docs", text: "Docs", active: "nested-url" },
116+
{ url: "/registry", text: "Registry", active: "nested-url" },
117+
{ url: "/contributors", text: "Contributors", active: "nested-url" }, // NEW
118+
{ url: "https://discord.gg/6xWPKhGDbA", text: "Discord", active: "none", external: true },
119+
],
120+
```
121+
122+
This places the Contributors tab alongside the existing Docs, Registry, and Discord tabs in the site header.
123+
124+
---
125+
126+
## 3. Contributors Page (Next.js)
127+
128+
### 3.1 Route Structure
129+
130+
All files under `src/app/(home)/contributors/` (inside the `(home)` route group, same pattern as the registry page):
131+
132+
```
133+
src/app/(home)/contributors/
134+
├── layout.tsx # Page layout wrapper
135+
├── page.tsx # Main contributors page
136+
└── contributor-card.tsx # Individual contributor card component
137+
```
138+
139+
### 3.2 Layout — `layout.tsx`
140+
141+
Simple layout wrapper matching the registry page style:
142+
- Centered container with `max-w-7xl`
143+
- Responsive padding (`px-4 pb-4 pt-6 sm:pt-12`)
144+
145+
### 3.3 Page — `page.tsx`
146+
147+
Statically imports `public/harbor_contribution.json` at build time (no runtime API calls).
148+
149+
**Three sections**:
150+
151+
| Section | Filter Logic | Description |
152+
|---------|-------------|-------------|
153+
| **Harbor Contributors** | At least one PR where `pr_type !== "adapter"` | Core framework contributors (67 people) |
154+
| **Harbor Adapter Contributors** | At least one PR where `pr_type === "adapter"` | Adapter/benchmark contributors (37 people) |
155+
| **Acknowledgments** | Static text | Credits section |
156+
157+
> Note: A contributor can appear in both sections if they have both adapter and non-adapter PRs.
158+
159+
**Grid layout**: Responsive grid (`1 col → 2 cols → 3 cols`) inside a bordered, rounded container.
160+
161+
### 3.4 Contributor Card — `contributor-card.tsx`
162+
163+
Each card is a clickable link to the contributor's GitHub profile. Uses shadcn/ui `Card`, `CardHeader`, `CardTitle`, `CardDescription`.
164+
165+
**Card contents** (minimal — name and handle only):
166+
- **Name** — `CardTitle`, monospace font (`font-code`), `text-lg`
167+
- **@handle** — `CardDescription`, monospace, `text-xs`
168+
169+
**Not displayed on cards** (available in data but excluded from UI):
170+
- Affiliation
171+
- PR count / additions / deletions
172+
173+
**Styling** (matches tbench.ai design):
174+
- `shadow-none`, `rounded-none` (flush grid tiles with shared borders)
175+
- `-mr-px -mt-px` offset on links for seamless tile borders
176+
- Hover: `hover:bg-sidebar dark:hover:bg-accent`
177+
- `transition-colors` for smooth hover animation
178+
179+
### 3.5 Acknowledgments Section
180+
181+
Static content rendered below the contributor grids:
182+
183+
```
184+
Acknowledgments
185+
186+
API inference compute for parity experiments is generously supported by
187+
2077AI (https://www.2077ai.com/).
188+
```
189+
190+
---
191+
192+
## 4. File Inventory
193+
194+
### New Files (12)
195+
196+
| File | Type | Description |
197+
|------|------|-------------|
198+
| `collect_pr_data.py` | Script | Collect merged PR data from GitHub |
199+
| `collect_user_data.py` | Script | Collect PR author profile info |
200+
| `generate_contributions.py` | Script | Aggregate, rank, and export contributions |
201+
| `raw_pr_data.json` | Data | Raw PR data (264 PRs) |
202+
| `raw_github_users_data.json` | Data | Raw user profile data (95 users) |
203+
| `harbor_contribution.json` | Data | Final aggregated contribution data (ranked by PR count) |
204+
| `public/harbor_contribution.json` | Data | Copy for Next.js static import |
205+
| `contributors_ready_to_show.csv` | Data | Webpage-only fields: handle, name, section flags |
206+
| `contributors.csv` | Data | Full contact info: handle, name, affiliation, email |
207+
| `src/app/(home)/contributors/layout.tsx` | Component | Page layout |
208+
| `src/app/(home)/contributors/page.tsx` | Component | Main page with 3 sections |
209+
| `src/app/(home)/contributors/contributor-card.tsx` | Component | Contributor card |
210+
211+
### Modified Files (1)
212+
213+
| File | Change |
214+
|------|--------|
215+
| `src/lib/layout.shared.tsx` | Added "Contributors" nav link |
216+
217+
---
218+
219+
## 5. Dependencies & Prerequisites
220+
221+
- **`gh` CLI**: Required for data collection scripts (must be authenticated with access to `laude-institute/harbor`)
222+
- **Python 3**: Required to run the data collection pipeline
223+
- **No new npm packages**: The page uses existing dependencies (shadcn/ui Card, Next.js Link, Fumadocs layout)
224+
225+
---
226+
227+
## 6. Local Development
228+
229+
```bash
230+
# 1. Install dependencies
231+
npm install # or: bun install
232+
233+
# 2. (Optional) Re-collect contributor data
234+
python collect_pr_data.py && python collect_user_data.py && python generate_contributions.py
235+
236+
# 3. Start dev server
237+
npm run dev
238+
239+
# 4. Visit http://localhost:3000/contributors
240+
```
241+
242+
---
243+
244+
## 7. Verification Checklist
245+
246+
- [x] `tsc --noEmit` — TypeScript type check passes (zero errors)
247+
- [x] `npm run build` — Production build compiles successfully
248+
- [x] Contributors page renders at `/contributors`
249+
- [x] Nav tab "Contributors" appears in site header
250+
- [x] Harbor Contributors section shows 67 contributors
251+
- [x] Harbor Adapter Contributors section shows 37 contributors
252+
- [x] Acknowledgments section displays 2077AI credit
253+
- [x] Cards link to correct GitHub profiles
254+
- [x] Cards display only name and @handle (no affiliation, no stats)
255+
- [x] Contributors ranked by PR count (descending)
256+
- [x] `contributors_ready_to_show.csv` generated with webpage-only fields
257+
- [x] `contributors.csv` generated with handle, name, affiliation, email
258+
- [x] Responsive grid layout (1/2/3 columns)
259+
- [x] Dark mode support

‎contributors.csv‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
github_handler,name,affiliation,email,is_adapter_contributor
2+
li-boxuan,Boxuan Li,Microsoft,,False
3+
alexgshaw,Alex Shaw,Laude Institute,alexgshaw64@gmail.com,False
4+
penfever,Ben Feuer,Stanford University,,False
5+
StevenDillmann,Steven Dillmann,Stanford University,,True
6+
CharlieFRuan,Charlie Ruan,UC Berkeley,,False
7+
ibercovich,Ivan Bercovich,ScOp Venture Capital,,False
8+
Slimshilin,Lin Shi,Cornell Tech,,True
9+
linhaowei1,Haowei Lin,Peking University,,True
10+
TheMikeMerrill,Mike Merrill,Stanford University,,False
11+
harshraj172,Harsh Raj,"Khoury College, Northeastern University ",,True
12+
neginraoof,Negin Raoof,UC Berkeley,,True
13+
chenzizhao,Zizhao Chen,Cornell Tech,,True
14+
mieciu,Przemysław Hejman,blindroot.com,,True
15+
LithiumDA,Shanda Li,Carnegie Mellon University,,True
16+
Ji-Pengliang,Pengliang Ji,Carnegie Mellon University,,True
17+
RishiDesai,Rishi Desai,,,False
18+
james-rl,James,Run Loop,,False
19+
AkshayVenkataraman,Akshay Venkataraman,,akshayv2k@gmail.com,False
20+
digitsisyph,Gary?,,,True
21+
lurf21,Ruofan Lu,The Chinese University of Hong Kong,,False
22+
jakozaur,Jacek Migdal,,jacek@migdal.pl,False
23+
dot-agi,Pratyush Shukla,Abundant AI,ps4534@nyu.edu,False
24+
luxinyu1,Solaris,ISCAS,,False
25+
michaelrglass,Michael Glass,IBM,,False
26+
connor-cognition,Connor Fogarty,Cognition AI,,False
27+
DannyGooo,Yonghui Liu,Monash University,,True
28+
octaviaguo,Ruohao Guo,Georgia Institute of Technology,,True
29+
HaishuoFang,Haishuo,TU Darmstadt,fanghaishuo@gmail.com,True
30+
Anjiang-Wei,Anjiang Wei,Stanford University,,True
31+
stared,Piotr Migdał,ex: Quantum Flytrap CTO & cofounder,pmigdal@gmail.com,False
32+
pfbyjy,Meji A,,,False
33+
thdxr,Dax,,mail@thdxr.com,False
34+
rotemtam,Rotem Tamir,honeybadge.co,,False
35+
paraliine,Xiaoxuan Peng,CQU,,False
36+
giansegato,gian,,,False
37+
tlongwell-block,tlongwell-block,,,False
38+
Chesars,Cesar Garcia,,,False
39+
HiromuHota,Hiromu Hota,https://snorkel.ai/,hiromu.hota@gmail.com,False
40+
EtashGuha,Etash Guha,Stanford University,,False
41+
KunWuLuan,GreenHand,,kunwuluan@gmail.com,False
42+
anishathalye,Anish Athalye,@joinhandshake,me@anishathalye.com,False
43+
WingchunSiu,Michael Siu,University of Southern California,,False
44+
josancamon19,Joan Cabezas,Based Hardware / Omi AI,,False
45+
beran-t,Berry,,,False
46+
tmacie,tmacie,,,False
47+
Michaelsqj,Qijia Shen,,shenqijia11@gmail.com,False
48+
self-supervisor,Augustine Mavor-Parker,VmaxAI,,False
49+
neverSettles,Chris Settles,"Operative AI, Inc",,False
50+
ZhengShenghan,Shenghan Zheng,Dartmouth College,shenghan.zheng.gr@dartmouth.edu,False
51+
likaixin2000,Kaixin Li,National University of Singapore,likaixin@u.nus.edu,False
52+
MarcoRossignoli,Marco Rossignoli,@microsoft,,False
53+
rohitpaulk,Paul Kuruvilla,@codecrafters-io,rohitpaulk@gmail.com,False
54+
Guangy627,Guangy627,,,False
55+
vatsj,Jacob Stavrianos,,jacobstavrianos@gmail.com,False
56+
Yiozolm,Fangzhou Yi,University of Science and Technology Beijing,m202310581@xs.ustb.edu.cn,False
57+
xdotli,Xiangyi Li,@benchflow-ai,xiangyi@benchflow.ai,False
58+
killthefullmoon,Hui Shen,University of Michigan,killthefullmoon@gmail.com,True
59+
1171-jpg,140,,,True
60+
xianliu,Xian Liu,Meetchances/ex-Bytedance/ex-Redhat,lxjsj@fedoraproject.org,True
61+
nandatheguntupalli,Nanda Guntupalli,,,False
62+
hanxu12,Han Xu,UIUC,,True
63+
kanazawa-asyncio,Kanaza,,,False
64+
Ternura143,Zixuan Zhu,NTU,,True
65+
EstelYang,Rui Yang,Peking University,ypyangrui@pku.edu.cn,True
66+
Hangzhi,Yiwei Dai,,hangzhiweiwei@gmail.com,True
67+
rootCircle,Lab Rat,"@uber, @iiitl ",,False
68+
terryyz,Terry Yue Zhuo,,terryzhuo25@gmail.com,True
69+
ifoukarakis,Ioannis Foukarakis,,,False
70+
Rebabit,Rebecca Deng,,,True
71+
Waterpine,Song Bian,University of Wisconsin-Madison,sbian8@wisc.edu,True
72+
avelanarius,Piotr Grabowski,@QuesmaOrg,,True
73+
bstee615,Benjamin Steenhoek,@Microsoft,benjaminjsteenhoek@gmail.com,False
74+
XuandongZhao,Xuandong Zhao,UC Berkeley,csxuandongzhao@gmail.com,True
75+
kobe0938,Kobe Chen,Stanford U,xiaokunchen0@gmail.com,True
76+
aht,Hai-Anh Trinh,grammarly.com,,True
77+
robertzhidealx,Robert Zhang,,0xrobertzhang@gmail.com,True
78+
dzorlu,Deniz Zorlu,Contextual AI,,False
79+
crystalxyz,Crystal Zhou,Cornell University,,True
80+
pashpashpash,Nik Pash,OpenAI,nik@cline.bot,False
81+
dpedchenko,Dmitrii Pedchenko,FAIR @ Meta MSL,,False
82+
richardzhuang0412,Richard Zhuang,Stanford University,,False
83+
ai-jz,ai-jz,,,False
84+
liyuyun-lyy,liyuyun-lyy,Alibaba,,False
85+
orfeas-menis,Orfeas Menis,,,True
86+
santaboi,Yang Fan Chiang,University of Maryland College Park,,False
87+
davidheineman,David Heineman,,david@davidheineman.com,True
88+
omi-n,nabil,"University of Washington, Microsoft",,True
89+
junhongmit,Junhong Lin,Massachusetts Institute of Technology,junhonghust@gmail.com,True
90+
MichaelY310,Michael Yang,UC Santa Barbara,,True
91+
ethanlshen,Ethan Shen,University of Washington,ethans03@cs.washington.edu,False
92+
Dongzhikang,Zhikang Dong,Stony Brook University,,True
93+
audreycs,Yuxin Wang,Dartmouth College,,True
94+
dines-rl,Alexander Dines,Run Loop,,False
95+
cliangyu,Leon Chen,Stanford University,,False
96+
tyler-griggs,Tyler Griggs,UC Berkeley,,False

0 commit comments

Comments
 (0)