investigating-open-source-projects

Investigating Open-Source Projects

Overview

Choose a research strategy based on the type of question. Different question types benefit from different tool combinations. GitHub's structured API tools excel at code-level and issue-level investigation; web search excels at finding blogs, release announcements, and ecosystem context.

Research Patterns

Implementation Discovery

Trigger: "How does X implement Y?" / "What patterns do libraries use for Z?"

Search for source code across repositories, then read implementations directly.

1. Search code with targeted queries scoped by repo, language, and path
2. Read 2-3 of the most relevant source files
3. Compare patterns across implementations

-- Find implementations
local results = github.search_code({
  query = 'symbol:retryWithBackoff language:typescript path:src NOT path:test'
}):await()

-- Read a file from results
local file = github.get_file_contents({
  owner = "some-org", repo = "some-repo", path = "src/retry.ts"
}):await()

result({ search = results, file = file })

Best for: finding how multiple projects solve the same problem. Especially strong for obscure libraries with sparse documentation — code search finds implementations that web search cannot.

Decision Archaeology

Trigger: "Why did project X choose Y over Z?" / "What alternatives were considered?"

Reasoning lives in issue discussions, PR comments, and blog posts. Search for the discussion, not the code.

1. Search issues and PRs in the project for the feature/decision
2. Read key issues to find debate and rationale
3. Check blog posts or release notes for additional context

-- Find relevant issues
local issues = github.search_issues({
  query = 'repo:prisma/prisma "json filtering" is:issue'
}):await()

-- Read an issue with comments
local detail = github.issue_read({
  owner = "prisma", repo = "prisma", issueNumber = 2444
}):await()

result({ issues = issues, detail = detail })

Best when combined with web search for blog posts and release announcements that explain the "why" in the team's own words.