Skip to content

README.md

Latest commit

 

History

History
351 lines (268 loc) · 13.6 KB

README.md

File metadata and controls

351 lines (268 loc) · 13.6 KB
 ██████╗ ██╗████████╗██╗  ██╗██╗   ██╗██████╗
██╔════╝ ██║╚══██╔══╝██║  ██║██║   ██║██╔══██╗
██║  ███╗██║   ██║   ███████║██║   ██║██████╔╝
██║   ██║██║   ██║   ██╔══██║██║   ██║██╔══██╗
╚██████╔╝██║   ██║   ██║  ██║╚██████╔╝██████╔╝
 ╚═════╝ ╚═╝   ╚═╝   ╚═╝  ╚═╝ ╚═════╝ ╚═════╝
      ██╗███████╗███████╗██╗   ██╗███████╗
      ██║██╔════╝██╔════╝██║   ██║██╔════╝
      ██║███████╗███████╗██║   ██║█████╗
      ██║╚════██║╚════██║██║   ██║██╔══╝
      ██║███████║███████║╚██████╔╝███████╗
      ╚═╝╚══════╝╚══════╝ ╚═════╝ ╚══════╝
 █████╗ ███╗   ██╗ █████╗ ██╗  ██╗   ██╗████████╗██╗ ██████╗███████╗
██╔══██╗████╗  ██║██╔══██╗██║  ╚██╗ ██╔╝╚══██╔══╝██║██╔════╝██╔════╝
███████║██╔██╗ ██║███████║██║   ╚████╔╝    ██║   ██║██║     ███████╗
██╔══██║██║╚██╗██║██╔══██║██║    ╚██╔╝     ██║   ██║██║     ╚════██║
██║  ██║██║ ╚████║██║  ██║███████╗██║      ██║   ██║╚██████╗███████║
╚═╝  ╚═╝╚═╝  ╚═══╝╚═╝  ╚═╝╚══════╝╚═╝      ╚═╝   ╚═╝ ╚═════╝╚══════╝

GitHub Issue Analytics 📊

CI Python 3.10+ License: MIT PyPI

Turn thousands of GitHub issues into actionable intelligence. ETL, metrics, heatmaps, dashboards.

Because at scale, you need data — not opinions.

📦 PyPI · 🤝 Contributing

🧠 The Problem

Hundreds of developers once signed an open letter about thousands of unresolved issues in a repo I manage.

The uncomfortable truth? I couldn't answer basic questions:

  • Which product areas are bleeding? No idea.
  • What's the actual fix rate? "We're working on it" isn't a number.
  • How old is the backlog — really? Months? Years?
  • Are things getting better or worse? Vibes don't count.

GitHub gives you issue counts. What you need is intelligence.

              GitHub Issues                              GitHub Issue Analytics
┌──────────────────────────────┐         ┌──────────────────────────────────────────┐
│  6,000+ open issues           │         │  Fix rate: 1.6% → 4.2% (↑163%)          │
│  "We're looking into it"     │  ───►   │  Median age: 847 days (P90: 1,842d)     │
│  Labels: ??? 🤷              │         │  Hotspot: Area-3 (38% of regressions)    │
│  Trend: ??? 📈📉❓            │         │  Stale attention: 127 items (>30d idle)  │
└──────────────────────────────┘         │  WoW trend: backlog ↓3.2%, TTFR ↑12%    │
                                         └──────────────────────────────────────────┘

⚡ Features

Feature What It Does
📥 ETL Pipeline Paginated GitHub REST API fetcher with rate limiting, caching, and incremental sync
📏 13-Metric Scorecard Fix rate, CPT, TIE, DSAT proxy, stale attention, regression rate, and more
🗺️ Area Heatmaps Product area × severity matrix — see which areas bleed at a glance
📊 HTML Dashboard Dark-themed interactive dashboard with 6 metric categories
📈 WoW Trending Week-over-week delta tracking with directional indicators
🏗️ Backlog Health Age distribution (7 buckets), unassigned rate, zero-comment, stale counts
🔄 Process Metrics Auto-closure patterns, ping-pong detection, assignee churn, response times
🏚️ Debt Analysis Regressions, breaking changes, API surface hotspots, platform fragmentation
💬 Engagement Scoring Reactions + comments + unique commenters = community signal strength
⚙️ YAML Config Define areas, labels, tracking patterns, thresholds — zero code changes
📋 Markdown Reports Stakeholder-ready reports with tables, deltas, and per-area breakdowns
💾 Snapshot History Weekly metric snapshots for long-term trend analysis

🏗️ Architecture

System Overview

flowchart TB
    subgraph INPUT["📥 Input"]
        GH["GitHub REST API<br/><code>issues + comments + timelines</code>"]
        CACHE["📁 Local Cache<br/><code>JSON snapshots</code>"]
    end

    subgraph ETL["🔄 ETL Pipeline"]
        FETCH["Paginated Fetcher<br/>Rate-limited"]
        CLASSIFY["Issue Classifier<br/>Label → structured fields"]
    end

    subgraph METRICS["📏 Metrics Engine"]
        direction LR
        CORE["Core Metrics<br/>CPT, TIE, Fix Rate"]
        PROCESS["Process Metrics<br/>TTFR, Ping-Pong, Churn"]
        DEBT["Debt Metrics<br/>Regressions, Breaking Changes"]
        HEAT["Heatmap Metrics<br/>Area DSAT, Volume, Risk"]
    end

    subgraph OUTPUT["📤 Output"]
        direction LR
        MD["📋 Markdown Report"]
        HTML["📊 HTML Dashboard"]
        JSON["💾 JSON Snapshot"]
    end

    GH --> FETCH
    CACHE --> CLASSIFY
    FETCH --> CLASSIFY
    CLASSIFY --> CORE
    CLASSIFY --> PROCESS
    CLASSIFY --> DEBT
    CLASSIFY --> HEAT
    CORE --> MD
    CORE --> HTML
    CORE --> JSON
    PROCESS --> HTML
    DEBT --> HTML
    HEAT --> HTML
Loading

Metric Categories

Category Metrics What It Reveals
Core Health CPT, TIE, DTC, NIR, Fix Rate, Backlog Overall repo health and throughput
Responsiveness TTFR, TTC, TTCl How fast you respond, triage, and close
Composite Scores SHS (0-100), DSAT Proxy Single-number health indicators
Process Auto-closure, Ping-pong, Assignee Churn Workflow efficiency and anti-patterns
Debt Regressions, Breaking Changes, Platform Fragmentation Technical debt accumulation
Heatmap Area DSAT, Monthly Volume, Engagement, Risk Where to focus attention

🚀 Quick Start

Install

pip install github-issue-analytics

Configure

Create a config.yaml in your project root:

repo: "owner/repo-name"

# Label taxonomy — map your repo's labels to structured categories
labels:
  areas:
    Frontend:
      - "area: frontend"
      - "component: ui"
    Backend:
      - "area: backend"
      - "area: api"
    Infrastructure:
      - "area: infra"
      - "area: devops"

  types:
    bug: ["bug", "type: bug"]
    feature: ["enhancement", "feature request", "type: feature"]
    question: ["question", "type: question"]
    regression: ["regression", "type: regression"]
    documentation: ["documentation", "type: docs"]

  statuses:
    triaged: ["status: triaged", "triaged"]
    in_progress: ["status: in progress", "in progress"]
    fixed: ["status: fixed", "fix committed"]
    wont_fix: ["wontfix", "status: won't fix"]
    needs_info: ["needs more info", "waiting for author"]

# Tracking ID patterns — detect linked work items
tracking_patterns:
  - name: "GitHub PR"
    pattern: '#\d+'
  - name: "Jira"
    pattern: '[A-Z]+-\d+'
  - name: "Linear"
    pattern: '[A-Z]+-[a-z0-9]+'

# Metric thresholds (for SHS scoring)
thresholds:
  target_fix_rate: 0.10          # 10% fix rate target
  target_median_age_days: 90     # 90-day median age target
  stale_days: 30                 # Days without activity = stale
  regression_penalty: 3          # Weight for open regressions in DSAT
  max_acceptable_ttfr_days: 7    # Target: first response within 7 days

# Org members (for response time calculations)
org_members:
  - "maintainer-bot"
  - "team-member-1"
  - "team-member-2"

# Bot accounts (excluded from community metrics)
bots:
  - "github-actions[bot]"
  - "dependabot[bot]"
  - "stale[bot]"

Analyze

# Full analysis — fetch + compute + report
gia analyze --config config.yaml

# Generate HTML dashboard
gia dashboard --config config.yaml --output report.html

# Use cached data (skip API fetch)
gia analyze --config config.yaml --cached

# Week-over-week trending
gia trending --config config.yaml

# Export metrics as JSON
gia export --config config.yaml --format json --output metrics.json

Python API

from github_issue_analytics import Analyzer

analyzer = Analyzer.from_config("config.yaml")

# Fetch and classify issues
issues = analyzer.fetch()
classified = analyzer.classify(issues)

# Calculate all metrics
metrics = analyzer.compute_metrics(classified)

print(f"Fix rate: {metrics.fix_rate:.1%}")
print(f"Median age: {metrics.median_age_days:.0f} days")
print(f"Service Health Score: {metrics.shs:.0f}/100")
print(f"Stale items: {metrics.stale_count}")

# Generate report
analyzer.generate_report(metrics, output="report.md")

# Generate dashboard
analyzer.generate_dashboard(metrics, output="dashboard.html")

📏 The 13 Metrics

Core Health

# Metric Full Name What It Measures
1 CPT Customer Pain Time Issue age distribution — mean, median, P90 by segment
2 TIE Time in Engineering Age of issues linked to work items (has tracking ID)
3 DTC Days to Close How long issues wait before resolution
4 NIR New Incident Rate Monthly filing trend with trailing averages
5 ER Escalation Rate Regressions + high-reaction + needs-attention composite
6 Fix Rate Fix Rate Percentage of issues at fixed/resolved status
7 Backlog Backlog Health Age brackets, unassigned rate, zero-comment, stale counts

Responsiveness

# Metric Full Name What It Measures
8 TTFR Time to First Response How fast org members respond to new issues
9 TTC Time to Triage Rate of untriaged issues (no status label)
10 TTCl Time to Close Wait time for near-close issues

Composite Scores

# Metric Full Name What It Measures
11 SHS Service Health Score Weighted 0–100 composite of all metrics
12 DSAT Dissatisfaction Proxy High-reaction + old-untracked + no-response + stale regressions
13 Per-Area Per-Area Breakdown All metrics sliced by configured area labels

🗺️ Dashboard Preview

The HTML dashboard provides 6 analysis categories:

Tab What You See
Process Auto-closure rates, response times, stale attention, backlog age distribution
Debt Regression trends, breaking changes, API hotspots, platform fragmentation
Heatmap Area × severity matrix, monthly volume trends, top engaged issues
DevEx Developer experience signals, documentation gaps, onboarding friction
Platform Cross-platform issues, version-specific problems
Versioning Version adoption curves, deprecation tracking

🔗 Cross-Repo Integration

GitHub Issue Analytics is part of the kustonaut PM toolchain:

Repo Integration
issue-sentinel Classification results feed into analytics as structured input
pm-signals Daily signal context enriches issue analysis
llm-eval-kit Quality checks for generated reports and dashboards

🧑‍💻 Development

# Clone
git clone https://github.com/kustonaut/github-issue-analytics.git
cd github-issue-analytics

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Lint
ruff check src/

📄 License

MIT — see LICENSE for details.

Built by @kustonaut — open-source tools for engineering teams at scale.