pr-report

# PR Report Generator Generate comprehensive PR reports for openshift/hypershift, openshift-eng/ai-helpers, openshift/enhancements, and openshift/release repositories. ## Usage ``` /pr-report # Last 7 days (default) /pr-report --start 2026-02-05 # From date to today /pr-report --start 2026-02-05 --end 2026-02-12 # Specific date range /pr-report --start 2026-02-05 --end 2026-02-12 --deep # With deep code analysis /pr-report --start 2026-02-05 --end 2026-02-12 --deep --progress-report # Deep analysis + progress report /pr-report --start 2026-02-05 --end 2026-02-12 --deep --breaking-changes # Deep analysis + breaking change report /pr-report --start 2026-05-14 --end 2026-06-22 --deep --progress-report --blog # Deep + progress report + blog post ``` **Parameters:** - `--start` (optional): Starting date in YYYY-MM-DD format (e.g., `2026-02-05`). Defaults to 7 days ago. - `--end` (optional): Ending date in YYYY-MM-DD format (e.g., `2026-02-12`). Defaults to today. - `--deep` (optional): Enable deep analysis mode that fetches and analyzes actual code diffs. - `--progress-report` (optional): Generate a narrative blog-style progress report (Dolphin Emulator style). **Requires `--deep`.** - `--breaking-changes` (optional): Generate a detailed breaking change assessment report for management cluster operators and senior SREs. **Requires `--deep`.** - `--blog` (optional): Generate a Material-styled blog post in `docs/content/blog/` and update `docs/mkdocs.yml` nav. **Requires `--progress-report`.** - `--output-dir` (optional): Directory for output files. If not specified, ask the user with AskUserQuestion. ## What This Command Does This command generates **two reports** (with two optional additions): ### 1. Fast Data Report (automated) - Fetches merged PRs from all repositories - Filters openshift/release PRs to only HyperShift-related paths - Filters openshift-eng/ai-helpers and openshift/enhancements PRs to HyperShift contributors - Queries Jira for ticket hierarchy (Epic, OCPSTRAT linkage) - Generates metrics (timing, reviewers, merge patterns) ### 2. Impact Analysis Report (LLM-generated) - Analyzes PR changes to assess actual impact - Groups work by themes and strategic initiatives - Provides context for project contributors and followers - Highlights notable changes, risks, and cross-repo dependencies ### 3. Deep Code Analysis (--deep mode only) - Fetches actual code diffs for selected PRs - Analyzes what the code actually changed (not just descriptions) - Identifies breaking changes, API modifications, test coverage - Verifies alignment between PR descriptions and actual changes ### 4. Progress Report (--progress-report, narrative blog post) - Narrative technical blog post in the style of Dolphin Emulator progress reports - Problem-first storytelling with technical depth - Credits contributors by GitHub handle - Thematic grouping of related changes ### 5. Breaking Change Report (--breaking-changes, SRE/management-oriented) - Identifies all PRs with breaking changes, API modifications, or behavioral shifts - Links each to Jira tickets with full hierarchy (ticket -> Epic -> OCPSTRAT) - Assesses impact scope per customer segment and usage pattern - Provides actionable recommendations (revert, fix, document, accept) - Written for management cluster operators and senior SREs ### 6. Collaboration Report (always generated with --deep) - Groups contributors into clusters based on review relationships and shared topics - Identifies bridge nodes who connect clusters - Super short format: one paragraph per cluster ### 7. Blog Post (--blog, docs-ready Material-styled post) - Converts progress report to MkDocs Material blog post with grid stat cards, admonitions, and icons - Generates sortable contributor table with per-repo linked PR counts and bugfix column - Creates/updates `docs/content/blog/index.md` landing page - Updates `docs/mkdocs.yml` nav with new post entry - Runs `make docs-aggregate` for verification - Applies sensitive content filtering for public blog (no S360/SFDC references) ## Output Files | File | Description | |------|-------------| | `$OUTPUT_DIR/weekly_pr_report_fast.md` | Data-focused report with metrics and PR listings | | `$OUTPUT_DIR/hypershift_pr_details_fast.json` | Raw PR data in JSON format | | `$OUTPUT_DIR/hypershift_pr_summary.json` | Compact summary data for LLM analysis | | `$OUTPUT_DIR/weekly_pr_report_impact.md` | LLM-generated impact analysis for contributors | | `$OUTPUT_DIR/pr_scored.json` | (--score) Ranked PR list for deep analysis | | `.work/pr_deep/*.json` | (--deep mode) Per-PR data with diffs for analysis | | `.work/pr_deep/*_analysis.json` | (--deep mode) Per-PR analysis results | | `.work/pr_deep_aggregated.json` | (--deep mode) Aggregated analysis findings | | `$OUTPUT_DIR/hypershift_progress_report_YYYY-MM-DD.md` | (--progress-report) Narrative progress report (blog-style) | | `$OUTPUT_DIR/breaking_changes_report_YYYY-MM-DD.md` | (--breaking-changes) Breaking change assessment for SREs | | `$OUTPUT_DIR/collaboration_report_YYYY-MM-DD.md` | (--deep) Contributor collaboration clusters | | `docs/content/blog/YYYY-MM-progress-report.md` | (--blog) Material-styled blog post for docs site | ## Implementation ### Step 0: Validate Arguments If `--progress-report` is specified without `--deep`, stop and inform the user: `--progress-report requires --deep mode for code-level analysis. Please add --deep to your command.` If `--blog` is specified without `--progress-report`, stop and inform the user: `--blog requires --progress-report mode to generate the blog source content. Please add --progress-report (and --deep) to your command.` ### Step 1: Run the Python script to fetch PRs Parse the arguments and run the script. The script accepts: - Positional `since_date` (start date) - `--end` flag for end date ```bash # Parse ARGUMENTS which may contain: --start YYYY-MM-DD --end YYYY-MM-DD --deep --output-dir DIR # Example: python3 contrib/repo_metrics/weekly_pr_report.py 2026-02-05 --end 2026-02-12 --output-dir /tmp # If --blog is specified, also pass --blog-data to generate blog_data.json python3 contrib/repo_metrics/weekly_pr_report.py $ARGUMENTS --output-dir $OUTPUT_DIR ``` Note: The script's positional argument is the start date. The `--start` flag in the skill is mapped to this positional argument when invoking the script. `$OUTPUT_DIR` is the directory chosen by the user. All output file paths below use this directory. When `--blog` is active, include `--blog-data` in the script arguments to generate `$OUTPUT_DIR/blog_data.json` with contributor table, metrics, and pre-rendered markdown. ### Step 2: Jira Enrichment (Conditional) Check the script output to determine if Jira data was fetched directly: **If script output shows "Fetching Jira data via REST API..."** (JIRA_EMAIL + JIRA_TOKEN were set): - Jira hierarchy was populated automatically by the script - Skip to Step 3 (Impact Analysis Report) **If script output shows "JIRA_EMAIL/JIRA_TOKEN not set, loading from cache"**: - Extract unique tickets from PR data and query Jira using MCP tools - Use `mcp__atlassian-mcp__jira_get_issue` for EACH ticket (in parallel) - **Fields to request:** `summary,description,parent,issuetype,customfield_10978,customfield_10979,customfield_10980,issuelinks,labels,priority,status` - **Key fields (Jira Cloud at redhat.atlassian.net):** - `parent` = native hierarchy field (includes key, summary, issuetype with hierarchyLevel) - `customfield_10978` = SFDC Cases Counter - `customfield_10979` = SFDC Cases Links - `customfield_10980` = SFDC Cases Open - **Hierarchy:** Walk the `parent` chain: Story/Bug (level 0) → Epic (level 1) → Feature (level 2, was OCPSTRAT) - Build hierarchy: ticket → Epic → Feature/OCPSTRAT - Save to `$OUTPUT_DIR/jira_hierarchy.json` - Re-run the Python script to regenerate report with enriched data ### Step 3: Generate Impact Analysis Report Read `$OUTPUT_DIR/hypershift_pr_details_fast.json` and `$OUTPUT_DIR/jira_hierarchy.json`, then generate a rich impact analysis report for project contributors and followers. **Write the report to `$OUTPUT_DIR/weekly_pr_report_impact.md`** following this structure: ```markdown # HyperShift Weekly Impact Report **Period:** YYYY-MM-DD to YYYY-MM-DD **Audience:** Project contributors and followers ## Summary [2-3 paragraphs summarizing the week's progress across all repositories. Highlight major themes, significant changes, and overall project momentum. Write in a tone suitable for developers and community members following the project.] ## Strategic Initiatives Progress [For each OCPSTRAT initiative with activity this week, provide:] ### OCPSTRAT-XXXX: [Initiative Name] **Status:** [Active development / Nearing completion / Maintenance] **This Week's Progress:** - [Bullet points describing meaningful progress, not just PR titles] - [Focus on what capability was added/fixed and why it matters] **PRs:** #XXX, #YYY, #ZZZ ## Repository Highlights ### openshift/hypershift [Group PRs by theme and explain their collective impact:] #### Platform Support - **AWS:** [What changed and why it matters] - **Azure/ARO:** [What changed and why it matters] - **GCP:** [What changed and why it matters] - **KubeVirt:** [What changed and why it matters] #### Control Plane [Significant changes to CPO, HO, or core controllers] #### Bug Fixes [Notable bugs resolved, grouped by severity/impact] #### Testing & Quality [Test improvements, CI fixes, coverage additions] ### openshift-eng/ai-helpers [Summarize AI tooling improvements and their impact on developer workflow] ### openshift/release [Summarize CI configuration changes grouped by category:] #### CI Efficiency [Job optimizations, resource adjustments] #### Test Coverage [New tests, validation improvements] #### Automation [Bot improvements, workflow automation] ## Notable PRs [Deep-dive on 3-5 high-impact PRs, selected by highest importance score from the `$OUTPUT_DIR/pr_scored.json` output (Jira priority, SDK/API changes, bug fixes, manual CI work). For each:] ### PR #XXXX: [Title] **Repository:** [repo] **Author:** @username **Why it matters:** [2-3 sentences explaining the actual impact of this change for users/developers] **What changed:** - [Technical summary of the key changes] - [Any breaking changes or migration notes] **Related:** [Links to related PRs, issues, or documentation] ## Risks & Breaking Changes [List any changes that could affect users or downstream consumers:] - **[Component]:** [Description of risk/change and mitigation] ## Dependencies & Cross-Repo Changes [Highlight changes that span multiple repositories or require coordinated updates] ## Metrics Snapshot | Metric | Value | |--------|-------| | Total PRs merged | X | | Unique contributors | X | | Avg time to merge | X hours | | Most active reviewer | @username (X PRs) | ## Coming Up [If visible from PR descriptions or Jira tickets, mention work in progress or upcoming features] ``` **Guidelines for Impact Analysis:** 1. **Audience is contributors and followers** - Use technical language appropriate for developers, but explain the "why" not just the "what" 2. **Assess actual impact** by reading PR descriptions and understanding: - What problem does this solve? - Who benefits from this change? - Does this enable new capabilities or fix broken functionality? 3. **Group related work** - Multiple PRs often contribute to one logical change; group them together 4. **Highlight cross-repo dependencies** - Changes in openshift/release often enable or support changes in hypershift 5. **Be specific about platforms** - HyperShift supports multiple platforms (AWS, Azure, GCP, KubeVirt, Agent); call out platform-specific work 6. **Call out breaking changes** - Any API changes, behavior changes, or deprecations should be prominently noted 7. **Recognize contributors** - Mention authors of significant work **Example Impact Transformations:** | PR Title | Impact Analysis | |----------|-----------------| | "OCPBUGS-60707: Fix user-ca-bundle cleanup when additionalTrustBundle is removed" | Fixes a bug where custom CA certificates persisted in guest clusters after being removed from HostedCluster spec. Operators managing trust bundles will now see expected cleanup behavior. | | "GCP-216: feat(nodepool): add GCP platform support" | Adds foundational NodePool support for GCP platform, enabling cluster autoscaling and machine management. This is a key milestone for GCP HyperShift availability. | | "CNTRLPLANE-2082: hypershift: run conformance directly on the root cluster" | Simplifies CI architecture by running conformance tests on the management cluster instead of nested clusters. Reduces resource requirements and test complexity. | ### Step 4: Deep Code Analysis (--deep mode only) If `--deep` flag is specified, perform deep code analysis after the standard report: #### Step 4a: Interactive PR Selection Present the user with PR selection options using AskUserQuestion: 1. Read `$OUTPUT_DIR/hypershift_pr_details_fast.json` and `$OUTPUT_DIR/jira_hierarchy.json` to categorize and score PRs. 2. **Score each PR using these criteria** (higher score = more important): | Criterion | Points | Description | |-----------|--------|-------------| | Enhancement proposal | +200 | openshift/enhancements PRs (always selected) | | Jira Priority: Critical/Blocker | +100 | Highest priority tickets | | Jira Priority: Major | +50 | Major priority tickets | | Jira Priority: Normal | +20 | Normal priority tickets | | Jira Priority: Minor | +10 | Minor priority tickets | | SDK/API/Migration work | +30 | Title contains "sdk", "migrate", "api", or "breaking" | | Feature work | +15 | Title contains "feat" or "feature" | | Bug fix (OCPBUGS) | +10 | Has OCPBUGS ticket reference | | Has any Jira ticket | +5 | Tracked work is more valuable | | Manual CI change | +10 | Non-bot author in openshift/release | To score PRs, join PR data with Jira hierarchy to get priority: ```bash # Get priority for a ticket from jira_hierarchy.json jq -r '."CNTRLPLANE-1708".priority' $OUTPUT_DIR/jira_hierarchy.json # Returns: "Critical" ``` 3. Ask user which PRs to analyze: ``` Options: - "All PRs (X total)" - Analyze every PR - "High-value selection (15-20 PRs)" - Auto-select top PRs by importance score - "Bug fixes only (Z PRs)" - OCPBUGS tickets only - "Custom selection" - Choose from annotated PR list ``` 4. If "High-value selection", sort PRs by score descending and select top 15-20. 5. If "Custom selection", present an **annotated PR list** for user selection: