Skip to content

README.md

Latest commit

 

History

History
275 lines (217 loc) · 9.57 KB

README.md

File metadata and controls

275 lines (217 loc) · 9.57 KB
Raw

GitHub PR Analytics Suite

🤖 AI-powered GitHub PR analytics tool that transforms your pull request history into professional markdown reports with intelligent project categorization, pattern analysis, and performance insights.

✨ Features

  • 📊 Pipeline Commands: Fetch, by-project, technical, and perf-review as separate steps
  • 🔄 Auto-fetch: Report commands re-run fetch if CSVs are missing
  • 🤖 AI-Powered Insights: Uses OpenAI to generate concise summaries and comprehensive pattern analysis
  • 📁 Project Categorization: Extracts project names from PR titles ([CS-1234] ProjectName: description)
  • 📝 Professional Reports: Generates beautiful markdown reports perfect for performance reviews
  • 🔍 Comprehensive Analysis: 5-section analysis covering project focus, technical themes, development velocity, cross-project insights, and key accomplishments
  • 📈 Smart Metrics: Tracks lines changed, PR distribution, and project priorities
  • 🎯 Performance Review Ready: Actionable insights for self-assessments and project planning

🏗️ Project Structure

pr/
├── src/
│   ├── github_pr_fetcher.py                     # Fetches PRs from GitHub
│   └── pr_summarizer.py                         # AI-powered analysis & summarization
├── output/
│   ├── pr_YYYY-MM-DD_YYYY-MM-DD_detailed.csv    # Raw PR data
│   ├── pr_YYYY-MM-DD_YYYY-MM-DD_summarized.csv  # With AI summaries
│   ├── pr_YYYY-MM-DD_YYYY-MM-DD_by_project.md
│   ├── pr_YYYY-MM-DD_YYYY-MM-DD_technical_highlights.md
│   └── pr_YYYY-MM-DD_YYYY-MM-DD_perf_review.md
├── main.py                                      # Complete workflow entry point
├── requirements.txt                             # Dependencies
├── .env.example                                 # Configuration template
└── README.md

🚀 Quick Start

1. Installation

git clone <your-repo>
cd pr
pip install -r requirements.txt

2. Setup

Create a .env file with your configuration:

cp .env.example .env

Edit .env and add your credentials:

# GitHub Configuration
GITHUB_TOKEN=your_personal_access_token_here
GITHUB_REPO=owner/repository
GITHUB_USERNAME=your_username  # Optional: specific user to search for

# Time range (pick one)
DAYS=14  # Past N days from today (default)
# START_DATE=2026-05-04  # Explicit range (both required; overrides DAYS)
# END_DATE=2026-05-08

# AI Configuration (for summarization)
OPENAI_API_KEY=your_openai_api_key_here
# OPENAI_MODEL=gpt-4o-mini  # optional; gpt-5* supported automatically

Getting GitHub Token

  1. Go to https://github.com/settings/tokens
  2. Click "Generate new token (classic)"
  3. Select scopes: repo (for private repos) or public_repo (for public repos)
  4. Copy the generated token

Getting OpenAI API Key

  1. Go to https://platform.openai.com/api-keys
  2. Create a new API key
  3. Copy the key (keep it secure!)

3. Run the pipeline

# Default: fetch + by-project + technical + publish to pr-reports
python main.py
# same as:
python main.py ship

# Or run steps individually:
python main.py fetch          # → _detailed.csv
python main.py summarize      # → _summarized.csv (from latest or --csv detailed)
python main.py by-project     # → _by_project.md
python main.py technical      # → _technical_highlights.md
python main.py perf-review    # → _perf_review.md
python main.py publish        # → commit in pr-reports clone
python main.py all            # fetch + all reports (no publish)

Report commands need both _detailed.csv and _summarized.csv. If missing, they run fetch and/or summarize as needed.

# Past N days (relative to today)
DAYS=7 python main.py ship

# Explicit date range (inclusive)
python main.py ship --start 2026-05-04 --end 2026-05-08

# Same via .env
START_DATE=2026-05-04 END_DATE=2026-05-08 python main.py fetch

# Publish and push
python main.py publish --push

# Re-run reports for an existing CSV (skips fetch)
python main.py by-project --csv output/pr_2026-05-04_2026-05-08_detailed.csv
Command What it does
fetch GitHub → _detailed.csv
summarize _detailed.csv → _summarized.csv (OpenAI)
by-project _summarized.csv → _by_project.md
technical _detailed.csv → _technical_highlights.md
perf-review _summarized.csv → _perf_review.md
publish Copy output/{prefix}* to PR_REPORTS_DIR and commit
all fetch + all three reports (no publish)
ship fetch + by-project + technical + publish

📊 Output Files

1. Detailed CSV (pr_YYYY-MM-DD_YYYY-MM-DD_detailed.csv)

Raw PR data with clean descriptions:

  • pr_url - Direct link to the PR
  • title - PR title
  • description - Clean description (removes boilerplate/templates)
  • lines_of_code_changes - Total lines changed
  • additions - Lines added
  • deletions - Lines deleted
  • created_at - PR creation timestamp
  • state - PR state (open/closed)
  • merged - Whether PR was merged
  • attachments - URLs of attachments found in PR

2. Summarized CSV (pr_YYYY-MM-DD_YYYY-MM-DD_summarized.csv)

All detailed data plus:

  • ai_summary - Concise AI-generated summary of each PR

3. Reports (markdown)

_perf_review.md

Professional markdown report with:

  • 📊 Executive Summary: Period, totals, averages
  • 🎯 Project Focus & Impact: Which projects got the most attention
  • ⚡ Technical Themes & Patterns: Performance, security, infrastructure initiatives
  • 🚀 Development Velocity & Scale: Work distribution and iteration patterns
  • 🔗 Cross-Project Insights: Shared challenges and dependencies
  • 🏆 Key Accomplishments & Trends: Significant achievements and innovation
  • 📋 Individual PR Details: Each PR with project categorization, status, and summary

🎯 Project Categorization

The tool intelligently extracts project names from PR titles using the format:

[TICKET-123] ProjectName: Summary of changes

Examples:

  • [CS-6304] Roles: DB schema for RBAC → Roles project
  • [CS-5916] Connector Catalog: update cypress tests → Connector Catalog project
  • [INFRA-123] Docker: Update base images → Docker project

PRs that don't match this pattern are categorized as "Uncategorized" and handled separately.

⚙️ Advanced Usage

Run Components Separately

# Just fetch PR data
python src/github_pr_fetcher.py

# Same commands via pr_summarizer directly
python src/pr_summarizer.py fetch
python src/pr_summarizer.py summarize
python src/pr_summarizer.py ship
python src/pr_summarizer.py publish
python src/pr_summarizer.py all

# Publish the latest (or a specific) output run to pr-reports
python src/publish_reports.py
python src/publish_reports.py --prefix pr_2026-05-09_2026-05-16 --push

Publish to pr-reports

Set PR_REPORTS_DIR in .env to your local clone of pr-reports, then:

python main.py publish
python main.py ship          # includes publish
python main.py publish --push

Copies every file matching the run prefix (CSVs and all report markdown files).

Time Range Options

# Last week
DAYS=7 python main.py

# Last month
DAYS=30 python main.py

# Last quarter
DAYS=90 python main.py

# Last year
DAYS=365 python main.py

🎨 Sample Output

Program output

🚀 Starting GitHub PR Analytics Suite
==================================================
📊 Step 1: Fetching PRs from GitHub...
Searching for PRs created by: xindixu
Time range: Past 180 day(s)
Fetching PRs from instabase/instabase created by 'xindixu' after 2025-01-15...
Found 325 PRs matching criteria
Added PR: [CS-6454] DS UI: Disable indexing modal should list connected chatbots (165 lines changed)
Added PR: [CS-6435] DS UI: Indexing items over limit + use real feature flag (165 lines changed)
Added PR: [CS-0000] Roles: GA in 25.30 (11 lines changed)
Added PR: [CS-6452] Roles: gate mount backend for create/edit/delete mount points (50 lines changed)
Processed 5/325 PRs...
...

Exported 325 PRs to output/pr_2025-01-15_2025-07-14_detailed.csv

Summary:
Total PRs found: 325
Total lines changed: 165431
Average lines per PR: 509.0
✅ PR data saved to: output/pr_2025-01-15_2025-07-14_detailed.csv

🤖 Step 2: Generating AI summaries...
📊 Loaded 325 PRs from output/pr_2025-01-15_2025-07-14_detailed.csv
✅ OpenAI client initialized with model: gpt-4o-mini
🤖 Generating AI summaries...
Processing PR 1/325: [CS-6454] DS UI: Disable indexing modal should lis...
Processing PR 2/325: [CS-6435] DS UI: Indexing items over limit + use r...
...
🔍 Analyzing patterns...
💾 Saved summarized data to output/pr_2025-01-15_2025-07-14_summarized.csv
📝 Saved pattern analysis to output/pr_2025-01-15_2025-07-14_summary.md

🎯 QUICK ANALYSIS
==================================================
...

🎉 WORKFLOW COMPLETE!
==================================================
📁 Detailed PR data: output/pr_2025-01-15_2025-07-14_detailed.csv
🤖 AI summarized data: output/pr_2025-01-15_2025-07-14_summarized.csv
📝 Pattern analysis: output/pr_2025-01-15_2025-07-14_summary.md

Example Files

Check out the examples/ directory for complete sample output demonstrating: