Skip to content

implementation_plan.md

Latest commit

 

History

History
82 lines (66 loc) · 4.25 KB

implementation_plan.md

File metadata and controls

82 lines (66 loc) · 4.25 KB
Raw

GitHub Multi-Repository Analytics & Monitoring Tool (github_tracker.py)

Create a complete, dedicated CLI solution (github_tracker.py) for monitoring software development metrics—commits, issues, pull requests, releases, and developer activity—across multiple GitHub projects in a centralized command center.

User Review Required

Important

Authentication & Rate Limits: GitHub's unauthenticated API allows only 60 requests/hour. The tool will support GITHUB_TOKEN (via environment variable or --token CLI option) to provide 5,000 requests/hour. A local cache (.github_tracker_cache.json) will be included to avoid wasting rate limits during repeated metric analysis.

Note

The tool supports specifying repositories directly via CLI (--repos facebook/react vercel/next.js ...), reading from a config file (repos.txt or repos.json), or auto-detecting GitHub remotes from local git clones.

Proposed Architecture & Features

Core Capabilities of github_tracker.py

  1. Multi-Project Metric Gathering:
    • Commits: Recent commit activity (last 7 / 30 days), latest commit timestamp and message, commit velocity.
    • Pull Requests: Open PR count, closed/merged PR count, stale PR indicator.
    • Issues: Open vs closed issue counts, open issue health.
    • Releases: Latest release tag, release publication date, total releases.
    • Languages & Code Stats: Top languages breakdown and repository size.
    • Engagement: Stars, forks, open watchers.
  2. Interactive & Visual Rich Terminal UI:
    • High-level KPI summary cards (Total Repos, Active PRs, Open Issues, Latest Releases).
    • Colorized comparison table displaying metrics side-by-side.
    • Project detail view (--detail owner/repo) providing deep breakdown of recent PRs, issues, and releases.
  3. Smart Caching & Rate Limit Management:
    • Caches responses locally to prevent API exhaustion.
    • Live display of remaining GitHub API quota.
    • --refresh flag to force fetch live updates.
  4. Export Engine:
    • Export multi-project status reports to Markdown (.md), CSV (.csv), and JSON (.json).

Proposed Changes

GitHub Analytics Component

[NEW] github_tracker.py

  • GitHubClient class: Handles GitHub REST API calls (/repos/{owner}/{repo}, /commits, /pulls, /issues, /releases), headers with optional Auth token, rate-limit headers checking, and response pagination.
  • RepoAnalyticsCollector: Concurrently fetches metrics for multiple repositories via concurrent.futures.
  • CacheManager: Persists metrics with timestamps in .github_tracker_cache.json.
  • RenderEngine: Rich terminal tables, status cards, detail panels, and progress bars.
  • ExportEngine: Generates structured reports in JSON, CSV, and Markdown table format.
  • CLI Parser: Supports --repos, --file, --detail, --refresh, --token, --sort, --export, and --clear-cache.

[NEW] repos.txt

  • Default sample project list (e.g. popular open-source projects or custom repos) so users can immediately run python github_tracker.py out of the box.

[MODIFY] requirements.txt

  • Add requests>=2.28.0 to ensure dependencies are documented alongside rich.

[MODIFY] Readme.md

  • Add section explaining github_tracker.py, GitHub API token setup, CLI arguments, and export features.

Verification Plan

Automated / CLI Verification

  1. Verify help menus and options: 
    python github_tracker.py --help
  2. Run sample multi-repo tracking on public repos (e.g. pallets/flask and tiangolo/fastapi): 
    python github_tracker.py --repos pallets/flask tiangolo/fastapi
  3. Test single project deep-dive: 
    python github_tracker.py --detail pallets/flask
  4. Test report export: 
    python github_tracker.py --repos pallets/flask --export test_analytics.md
  5. Test cache hit and refresh behavior: 
    python github_tracker.py
python github_tracker.py --refresh