/summarize-jiras

Name

component-health:summarize-jiras

Synopsis

/component-health:summarize-jiras --project <project> [--component comp1 comp2 ...] [--status status1 status2 ...] [--include-closed] [--limit N]

Description

The component-health:summarize-jiras command queries JIRA bugs for a specified project and generates summary statistics. It leverages the list-jiras command to fetch raw JIRA data and then calculates counts by status, priority, and component to help understand the bug backlog at a glance.

By default, the command includes:

• All currently open bugs
• Bugs closed in the last 30 days (to track recent closure activity)

This command is useful for:

• Getting a quick count of open bugs in a JIRA project
• Analyzing bug distribution by status, priority, or component
• Tracking recent bug flow (opened vs closed in last 30 days)
• Generating summary reports for bug backlog
• Monitoring bug velocity and closure rates by component
• Comparing bug counts across different components

Implementation

1. Verify Prerequisites: Check that Python 3 is installed

   • Run: python3 --version
   • Verify version 3.6 or later is available

2. Verify Environment Variables: Ensure JIRA authentication is configured

   • Check that the following environment variables are set:

     • JIRA_URL: Base URL for JIRA instance (e.g., "https://issues.redhat.com")
     • JIRA_PERSONAL_TOKEN: Your JIRA bearer token or personal access token

   • Verify with:

     echo "JIRA_URL: ${JIRA_URL}"
     echo "JIRA_PERSONAL_TOKEN: ${JIRA_PERSONAL_TOKEN:+***set***}"
     

   • If missing, guide the user to set them:

     export JIRA_URL="https://issues.redhat.com"
     export JIRA_PERSONAL_TOKEN="your-token-here"
     

3. Parse Arguments: Extract project key and optional filters from arguments

   • Project key: Required --project flag (e.g., "OCPBUGS", "OCPSTRAT")
   • Optional filters:
     • --component: Space-separated list of component search strings (fuzzy match)
     • --status: Space-separated list of status values
     • --include-closed: Flag to include closed bugs
     • --limit: Maximum number of issues to fetch per component (default: 1000, max: 1000)

4. Resolve Component Names (if component filter provided): Use fuzzy matching to find actual component names

   • Extract release from context or ask user for release version
   • Run list_components.py to get all available components:

     python3 plugins/component-health/skills/list-components/list_components.py --release <release>
     

   • For each search string in --component:
     • Find all components containing that string (case-insensitive)
     • Combine all matches into a single list
     • Remove duplicates
     • If no matches found for a search string, warn the user and show available components

5. Execute Python Script: Run the summarize_jiras.py script for each component

   • Script location: plugins/component-health/skills/summarize-jiras/summarize_jiras.py
   • The script internally calls list_jiras.py to fetch raw data
   • Important: Iterate over each resolved component separately to avoid overly large queries
   • For each component:
     • Build command with project, single component, and other filters
     • Execute: python3 summarize_jiras.py --project <project> --component "<component>" [other args]
     • Capture JSON output from stdout
   • Aggregate summary statistics from all components into a combined response

6. Parse Output: Process the aggregated JSON response

   • Extract summary statistics:
     • total_count: Total matching issues in JIRA
     • fetched_count: Number of issues actually fetched
     • summary.by_status: Count of issues per status
     • summary.by_priority: Count of issues per priority
     • summary.by_component: Count of issues per component
   • Extract per-component breakdowns:
     • Each component has its own counts by status and priority
     • Includes opened/closed in last 30 days per component

7. Present Results: Display summary in a clear format

   • Show which components were matched (if fuzzy search was used)
   • Show total bug count across all components
   • Display status breakdown (e.g., New, In Progress, Verified, etc.)
   • Display priority breakdown (Critical, Major, Normal, Minor, etc.)
   • Display component distribution
   • Show per-component breakdowns with status and priority counts
   • Highlight any truncation (if fetched_count < total_count for any component)
   • Suggest increasing --limit if results are truncated

8. Error Handling: Handle common error scenarios

   • Network connectivity issues
   • Invalid JIRA credentials
   • Invalid project key
   • HTTP errors (401, 404, 500, etc.)
   • Rate limiting (429)

Return Value

The command outputs a JIRA Bug Summary with the following information:

Project Overview

• Project: JIRA project key
• Total Count: Total number of matching bugs (open + recently closed)
• Query: JQL query that was executed (includes 30-day closed bug filter)
• Fetched Count: Number of bugs actually fetched (may be less than total if limited)

Summary Statistics

Overall Metrics:

• Total bugs fetched
• Bugs opened in last 30 days
• Bugs closed in last 30 days

By Status: Count of bugs in each status (includes recently closed)

Status	Count
New	X
In Progress	X
Verified	X
Closed	X
...	...

By Priority: Count of bugs by priority level

Priority	Count
Critical	X
Major	X
Normal	X
Minor	X
Undefined	X

By Component: Count of bugs per component

Component	Count
kube-apiserver	X
Management Console	X
Networking	X
...	...

Per-Component Breakdown

For each component:

• Total: Number of bugs assigned to this component
• Opened (30d): Bugs created in the last 30 days
• Closed (30d): Bugs closed in the last 30 days
• By Status: Status distribution for this component
• By Priority: Priority distribution for this component

Additional Information

• Filters Applied: Lists any component, status, or other filters used
• Note: If results are truncated, suggests increasing the limit
• Query Scope: By default includes open bugs and bugs closed in the last 30 days

Examples

1. Summarize all open bugs for a project:

   /component-health:summarize-jiras --project OCPBUGS
   

   Fetches all open bugs in the OCPBUGS project (up to default limit of 1000) and displays summary statistics.

2. Filter by specific component:

   /component-health:summarize-jiras --project OCPBUGS --component "kube-apiserver"
   

   Shows bug counts for only the kube-apiserver component.

3. Filter by multiple components:

   /component-health:summarize-jiras --project OCPBUGS --component "kube-apiserver" "etcd" "Networking"
   

   Shows bug counts for kube-apiserver, etcd, and Networking components.

4. Include closed bugs:

   /component-health:summarize-jiras --project OCPBUGS --include-closed --limit 500
   

   Includes both open and closed bugs, fetching up to 500 issues.

5. Filter by status:

   /component-health:summarize-jiras --project OCPBUGS --status New "In Progress" Verified
   

   Shows only bugs in New, In Progress, or Verified status.

6. Combine multiple filters:

   /component-health:summarize-jiras --project OCPBUGS --component "Management Console" --status New Assigned --limit 200
   

   Shows bugs for Management Console component that are in New or Assigned status.

Arguments

• --project <project> (required): JIRA project key

  • Format: Project key in uppercase (e.g., "OCPBUGS", "OCPSTRAT")
  • Must be a valid JIRA project you have access to

• Additional optional flags:

  • --component <search1> [search2 ...]: Filter by component names using fuzzy search

    • Space-separated list of component search strings
    • Case-insensitive substring matching
    • Each search string matches all components containing that substring
    • Makes separate JIRA queries for each matched component to avoid overly large results
    • Example: "network" matches "Networking / ovn-kubernetes", "Networking / DNS", etc.
    • Example: "kube-" matches "kube-apiserver", "kube-controller-manager", etc.
    • Note: Requires release context (inferred from recent commands or specified by user)

  • --status <status1> [status2 ...]: Filter by status values

    • Space-separated list of status names
    • Examples: New, "In Progress", Verified, Modified, ON_QA

  • --include-closed: Include closed bugs in results

    • By default, only open bugs are returned
    • When specified, closed bugs are included

  • --limit <N>: Maximum number of issues to fetch per component

    • Default: 1000
    • Range: 1-1000
    • When using component filters, this limit applies to each component separately
    • Higher values provide more accurate statistics but slower performance

Prerequisites

1. Python 3: Required to run the data fetching and summarization scripts

   • Check: which python3
   • Version: 3.6 or later

2. JIRA Authentication: Environment variables must be configured

   • JIRA_URL: Your JIRA instance URL
   • JIRA_PERSONAL_TOKEN: Your JIRA bearer token or personal access token

   How to get a JIRA token:

   • Navigate to JIRA → Profile → Personal Access Tokens
   • Generate a new token with appropriate permissions
   • Export it as an environment variable

3. Network Access: Must be able to reach your JIRA instance

   • Ensure HTTPS requests can be made to JIRA_URL
   • Check firewall and VPN settings if needed

Notes

• The script uses Python's standard library only (no external dependencies)
• Output is JSON format for easy parsing
• Diagnostic messages are written to stderr, data to stdout
• The script has a 30-second timeout for HTTP requests
• For large projects, consider using component filters to reduce query size
• Summary statistics are based on fetched issues (controlled by --limit), not total matching issues
• If results show truncation, increase the --limit parameter for more accurate statistics
• This command internally uses /component-health:list-jiras to fetch raw data

See Also

• Skill Documentation: plugins/component-health/skills/summarize-jiras/SKILL.md
• Script: plugins/component-health/skills/summarize-jiras/summarize_jiras.py
• Related Command: /component-health:list-jiras (for raw JIRA data)
• Related Command: /component-health:analyze