oss-evaluate-repo

name	oss-evaluate-repo
description	Evaluate whether an OSS repo is worth long-term investment before committing time. Assesses project health, governance, community, bus factor, and trajectory. Use when deciding whether to contribute to a specific repo, choosing between multiple repos, or evaluating a project's sustainability. Not for checking if a repo accepts contributions — use oss-find-issue for that.

Evaluate Repo

Is this repo worth your time? Not every open source project deserves months of contribution effort. This skill evaluates project health, governance, community dynamics, and trajectory — so you invest in repos that will value your work and still exist in a year.

Purpose

Contributing to OSS is an investment. A single meaningful PR takes 10-40 hours including learning the codebase. Before investing that time, you should know: Is this project actively maintained? Is the community healthy? Will your contributions be reviewed? Could the project be abandoned next month? This skill answers those questions with evidence, not vibes.

When to Use

• Deciding whether to invest time in a specific OSS project
• Choosing between multiple repos to contribute to
• Evaluating a project before committing to a GSoC proposal
• NOT for checking if a repo accepts external contributions — oss-find-issue does that
• NOT for evaluating code quality — oss-explore-repo does that
• NOT for repos you're already contributing to — too late, you're invested

Prerequisites

• A repo URL or name to evaluate
• gh CLI authenticated
• Clear goals for why you want to contribute (learning, career, community)

Process

1. Check vital signs

These are binary health checks — if any fail, the repo is likely not worth investing in.

# Basic repo info
gh api repos/{owner}/{repo} --jq '{
  stars: .stargazers_count,
  forks: .forks_count,
  open_issues: .open_issues_count,
  archived: .archived,
  license: .license.spdx_id,
  created: .created_at,
  updated: .pushed_at,
  default_branch: .default_branch
}'

# Recent commit activity
git log --oneline -20 --since="6 months ago" 2>/dev/null || \
  gh api repos/{owner}/{repo}/commits --jq '.[0:10] | .[] | "\(.commit.author.date[:10]) \(.commit.message | split("\n")[0])"'

# Is the repo archived or in maintenance mode?
gh api repos/{owner}/{repo} --jq '.archived'

Kill signals (stop evaluation if any are true):

• Archived or read-only
• No commits in 6+ months
• README says "no longer maintained" or "looking for maintainers"
• License is missing or incompatible with your needs

2. Assess governance and bus factor

Who runs this project, and what happens if they leave?

# Top contributors (bus factor check)
gh api repos/{owner}/{repo}/contributors --jq '.[0:10] | .[] | "\(.contributions)\t\(.login)"'

# Recent committers (who's active NOW, not historically)
gh api repos/{owner}/{repo}/commits --jq '[.[0:50] | .[].author.login // "unknown"] | sort | group_by(.) | map({user: .[0], commits: length}) | sort_by(-.commits) | .[0:5] | .[] | "\(.commits)\t\(.user)"'

# Check if it's an org or personal project
gh api repos/{owner}/{repo} --jq '.owner.type'

Evaluate:

• Bus factor: How many people have committed in the last 3 months? If it's 1, the project dies if they stop.
• Org vs personal: Org-backed projects are more sustainable. Personal projects depend on one person's motivation.
• Corporate backing: Check if contributors have @company emails or if the org is a company. Corporate-backed OSS has resources but may shift priorities.
• Governance model: Is there a GOVERNANCE.md? A code of conduct? A clear decision-making process?

3. Evaluate community health

A healthy community means your contributions get reviewed, your questions get answered, and conflicts get resolved.

# Issue responsiveness — how quickly do issues get responses?
gh issue list -R {owner}/{repo} --state closed --limit 20 --json number,createdAt,closedAt,comments \
  --jq '.[] | {number, created: .createdAt[:10], closed: .closedAt[:10], comments: .comments}'

# PR review turnaround
gh pr list -R {owner}/{repo} --state merged --limit 20 --json number,createdAt,mergedAt,reviews \
  --jq '.[] | {number, created: .createdAt[:10], merged: .mergedAt[:10], reviews: (.reviews | length)}'

# Check for toxic interactions (look at recent closed issues/PRs)
gh issue list -R {owner}/{repo} --state closed --limit 5 --json number,comments \
  --jq '.[].number' | while read n; do
    echo "=== Issue #$n ==="
    gh issue view $n -R {owner}/{repo} --json comments --jq '.comments[-3:] | .[].body' | head -20
  done

Healthy signals:

• Issues get responses within a week
• PRs get reviewed within 2 weeks
• Maintainers are polite and constructive
• External contributors' PRs actually get merged
• Disagreements are resolved respectfully

Unhealthy signals:

• Issues and PRs sit for months without response
• Maintainer tone is dismissive or aggressive
• External PRs get closed without explanation
• Community discussions are toxic or absent
• "Drive-by" maintainer activity (once a month, closes 20 issues, disappears)

4. Check release cadence and stability

# Recent releases
gh release list -R {owner}/{repo} --limit 10

# Release frequency
gh release list -R {owner}/{repo} --limit 10 --json tagName,publishedAt \
  --jq '.[] | "\(.publishedAt[:10])\t\(.tagName)"'

Evaluate:

• Regular releases: Monthly or quarterly releases signal active development
• Stale releases: Last release 2+ years ago means your contributions won't reach users
• Breaking changes: Frequent major versions suggest instability
• Changelog quality: Detailed changelogs signal mature project management

5. Evaluate CI and development practices

# CI configuration
ls .github/workflows/ 2>/dev/null
cat .github/workflows/ci.yml 2>/dev/null | head -30

# Code quality tools
ls .eslintrc* .prettierrc* pyproject.toml rustfmt.toml .editorconfig 2>/dev/null

# Test infrastructure
find . -name "*test*" -type d -maxdepth 3 2>/dev/null | head -10

Mature project signals:

• CI runs on PRs (not just main)
• Linting and formatting enforced
• Test suite exists and is maintained
• Code review is required (branch protection)

6. Thinking gate — user articulates the decision

Present all findings in a structured summary and ask:

"Based on everything we've found:

1. What's the strongest argument FOR contributing to this repo?
2. What's the biggest risk? (Bus factor, community health, stale reviews?)
3. Does this repo align with YOUR goals? (What do you want to learn or achieve?)
4. If this project were abandoned in 6 months, would your contributions still have been worth it for the learning alone?"

Wait for their answer. The last question is the most important — if the answer is no, the repo isn't worth the investment regardless of current health.

7. Make the decision

Based on the evaluation, the user decides:

• Go: Project is healthy, community is welcoming, goals align → proceed to oss-find-issue
• Wait: Project has potential but some concerns → bookmark and re-evaluate in a month
• Pass: Project has kill signals or doesn't align with goals → look for a different repo

Related Skills

• Next step (if Go): → oss-explore-repo — explore the codebase before contributing
• Next step (if Go): → oss-find-issue — find an issue to work on
• Alternative: → oss-find-real-issues — if the repo is healthy but has no labeled issues

Common Rationalizations

Shortcut	Why It Fails
"It has 50k stars, it must be healthy"	Stars measure popularity, not health. Many starred repos are unmaintained, have toxic communities, or don't merge external PRs.
"The code is interesting, that's enough"	Interesting code with an absent maintainer means your PR sits for months. The maintainer relationship matters as much as the code.
"I'll just contribute and see what happens"	Contributing without evaluating wastes 10-40 hours when your PR gets ignored. 30 minutes of evaluation saves weeks of frustration.
"It's backed by a big company, so it's safe"	Companies shift priorities. Corporate OSS projects get abandoned when the sponsoring team pivots. Check the actual activity, not the logo.
"I don't have time to evaluate, I just want to code"	Evaluation IS the most valuable use of your time. A well-chosen repo multiplies the impact of every hour you spend contributing.

Red Flags

• All recent commits are from a single person — extreme bus factor risk
• Issues and PRs from 6+ months ago sit unanswered — maintainer has checked out
• README promises features that don't exist — project is aspirational, not real
• Frequent hostile interactions in issues/PRs — toxic community
• User can't articulate why THIS repo over alternatives — they're picking randomly

Verification Checklist

• Vital signs checked — not archived, recent commits exist, license verified (step 1)
• Bus factor assessed — multiple active contributors, org vs personal (step 2)
• Community health evaluated — response times, tone, external PR merge rate (step 3)
• Release cadence checked — regular releases reaching users (step 4)
• CI and dev practices assessed — tests, linting, code review (step 5)
• User articulated go/wait/pass decision with reasoning (step 6-7)

Anti-patterns

• DO NOT evaluate based on stars alone — stars measure awareness, not health
• DO NOT skip the community health check — a technically excellent project with a toxic community isn't worth contributing to
• DO NOT evaluate for the user — present the evidence and let them decide
• DO NOT recommend repos you haven't evaluated — every recommendation needs evidence
• DO NOT rush the evaluation to start coding faster — 30 minutes of evaluation saves weeks of wasted effort