--- name: find-best-reviewers description: Find the best code reviewers in a GitHub repository or for specific file paths — uses GraphQL to analyze PR review history, filters bots, weights review states, surfaces domain specialists keywords: reviewer, review, code review, who reviews, CODEOWNERS, PR, pull request, maintainer, contributor, domain expert, github related: [oss-repo-recon, github-trending-repos, pr-lifecycle] --- # Find Best Reviewers Discover who actually reviews code in a GitHub repository. Answers two questions: 1. "Who should review my PR?" (path-aware) 2. "Who are the top reviewers in this repo?" (repo-wide) ## When to Use - Before submitting a PR to an unfamiliar repo — find who to expect reviews from - During oss-repo-recon — identify key maintainers - When CODEOWNERS is missing or incomplete - When scoping a contribution — find who owns a subsystem ## Parameters - **repoFullName**: `owner/repo` (required) - **paths**: list of file paths to filter by (optional — omit for repo-wide ranking) - **topic**: topic keyword for global discovery mode (optional — omit for single-repo) ## Step 0: Check CODEOWNERS Before doing any analysis, check if the repo already answers the question: ```bash # Check both standard locations gh api repos/{owner}/{repo}/contents/CODEOWNERS --jq '.content' 2>/dev/null | base64 -d gh api repos/{owner}/{repo}/contents/.github/CODEOWNERS --jq '.content' 2>/dev/null | base64 -d ``` If CODEOWNERS exists and covers the target paths, report those owners. Still run the analysis below to supplement — CODEOWNERS can be stale or incomplete. ## Step 1: Fetch PR + Review Data via GraphQL Use a single GraphQL query to fetch merged PRs with nested reviews and file paths. This is ~100x more efficient than REST (1 call vs 200+). ```bash gh api graphql -f query=' query($owner: String!, $repo: String!, $cursor: String) { repository(owner: $owner, name: $repo) { pullRequests( states: MERGED first: 100 after: $cursor orderBy: {field: UPDATED_AT, direction: DESC} ) { pageInfo { hasNextPage endCursor } nodes { number mergedAt files(first: 100) { nodes { path } } reviews(first: 50) { nodes { author { login } state submittedAt } } } } } }' -f owner=OWNER -f repo=REPO > /tmp/reviewer_data.json ``` **Pagination:** If `hasNextPage` is true and the oldest PR's `mergedAt` is within 6 months, fetch the next page using `endCursor`. Stop when you exceed the 6-month window. **Why time-window, not count-window:** "Last 200 PRs" means 10 days for rust-lang/rust but 8 years for a small project. A 6-month window produces comparable results regardless of repo velocity. **Omit `files` field** if you only need repo-wide ranking (Tool 2) — it halves the response size. ## Step 2: Analyze with Python Save the JSON from Step 1, then run this analysis: ```python import json from collections import defaultdict with open("/tmp/reviewer_data.json") as f: data = json.load(f) prs = data["data"]["repository"]["pullRequests"]["nodes"] # 6-month cutoff (adjust date to current) cutoff = "YYYY-MM-DD" # 6 months ago from today recent_prs = [pr for pr in prs if pr["mergedAt"] and pr["mergedAt"] >= cutoff] # --- Path filtering (Tool 1 only) --- # Uncomment and set target_paths for path-aware mode # target_paths = ["src/server/", "src/core/types"] # recent_prs = [pr for pr in recent_prs # if any(any(p.startswith(tp) for tp in target_paths) # for p in [f["path"] for f in pr["files"]["nodes"]])] # Bot detection BOTS = { "dependabot", "renovate", "renovate-bot", "github-actions", "codecov", "netlify", "vercel", "graphite-app", "copilot-pull-request-reviewer", "bors", "triagebot", "mergify", "stale", "allcontributors", "greenkeeper", } def is_bot(login): return login.lower() in BOTS or "[bot]" in login.lower() # Score reviewers scores = defaultdict(lambda: { "weighted": 0, "approved": 0, "changes_requested": 0, "commented": 0, "total": 0, "last_review": "" }) for pr in recent_prs: for review in pr["reviews"]["nodes"]: if not review["author"]: continue login = review["author"]["login"] if is_bot(login): continue state = review["state"] s = scores[login] s["total"] += 1 # Weight: decision-making reviews count double if state == "APPROVED": s["approved"] += 1 s["weighted"] += 2 elif state == "CHANGES_REQUESTED": s["changes_requested"] += 1 s["weighted"] += 2 elif state == "COMMENTED": s["commented"] += 1 s["weighted"] += 1 if review["submittedAt"] and review["submittedAt"] > s["last_review"]: s["last_review"] = review["submittedAt"] # Rank and display ranked = sorted(scores.items(), key=lambda x: (-x[1]["weighted"], -x[1]["total"])) for i, (login, s) in enumerate(ranked[:20], 1): last = s["last_review"][:10] if s["last_review"] else "n/a" print("%-4d %-25s score=%-6d approved=%-4d changes=%-4d comments=%-4d total=%-4d last=%s" % ( i, login, s["weighted"], s["approved"], s["changes_requested"], s["commented"], s["total"], last)) ``` ## Step 3: Interpret Results ### Reading the output - **Score** = `(approved * 2) + (changes_requested * 2) + (commented * 1)`. Decision-makers rank higher than drive-by commenters. - **Approved vs Changes Requested** — high changes_requested ratio suggests a thorough gatekeeper. - **Last Review date** — check recency. A top reviewer from 5 months ago may have moved on. - **Path-filtered vs repo-wide** — the most valuable insight comes from comparing the two. Domain specialists invisible in repo-wide rankings often surface in path-filtered results. ### What this does NOT measure - **Review quality** — review count doesn't tell you if reviews catch bugs. There's no reliable API signal for this (revert correlation is too noisy). - **Review depth** — a 1-line "LGTM" approval counts the same as a 50-comment deep dive. Optional enrichment (Step 4) partially addresses this. - **Availability** — the top reviewer by history may be on vacation or burned out. ## Step 4: Optional Enrichment Only run this if the baseline ranking needs more detail. For the top N reviewers from Step 2, fetch review comments to measure depth: ```graphql query($owner: String!, $repo: String!, $prNumber: Int!) { repository(owner: $owner, name: $repo) { pullRequest(number: $prNumber) { reviews(first: 50) { nodes { author { login } comments(first: 100) { totalCount } } } } } } ``` Enrichment signals: - **Comment density** — avg inline comments per review (thoroughness) - **File breadth** — distinct directories reviewed (generalist vs specialist) - **Recency curve** — are they ramping up or winding down? ## Tool 3: Global Discovery (by topic) Find top reviewers across multiple repos in a domain: ```bash # Find top 3 repos for a topic gh api 'search/repositories?q=topic:TOPIC+language:LANG&sort=stars&per_page=3' \ --jq '.items[].full_name' ``` Then run Steps 1-2 on each repo. **Present results per-repo** — never blend scores across repos (a #1 reviewer in a 50-person repo isn't comparable to #1 in a 5000-person repo). ## Design Decisions | Decision | Rationale | |----------|-----------| | GraphQL over REST | 1 call fetches 100 PRs + reviews. REST needs 200+ calls for the same data | | Time-window (6mo) over count-window (200 PRs) | Comparable results across repos of different velocities | | State weighting (APPROVED/CHANGES_REQUESTED = 2x) | Distinguish decision-makers from drive-by commenters | | Client-side path filtering | GitHub search API doesn't support `path:` for PR queries | | No defect catch rate | Reverts happen for many reasons (priority, refactors) — too noisy | | No turnaround time | Measures availability, not quality. Penalizes different timezones | | No NLP on comment bodies | Keyword heuristics ("nit") have terrible precision on real data | | No cross-repo blended scores | Apples-to-oranges comparison | | CODEOWNERS checked first | Don't re-solve problems that are already solved | ## Known Limitations 1. **Bot-heavy repos** (rust-lang/rust with bors) may have sparse review data — reviews happen via PR comments, not GitHub's review system. 2. **Files field truncation** — PRs with 100+ changed files get truncated. These are usually mechanical changes so the impact on reviewer discovery is low. 3. **Private repos** require a token with appropriate scopes. 4. **Review count favors availability** — someone who rubber-stamps 100 trivial PRs outranks someone who deeply reviews 10 critical ones. State-weighting partially mitigates this. 5. **GraphQL rate limit** — 5000 points/hour. Each paginated query costs ~1 point per 100 nodes. Fine for single-repo; budget carefully for multi-repo scans.