zhongwei/gh-openshift-eng-ai-helpers-plugins-jira

Files

Zhongwei Li 2109c2330b Initial commit

2025-11-30 08:46:00 +08:00

14 KiB

Raw Blame History

name, description, command

name	description	command
JIRA Release Blocker Validator	Detailed implementation guide for validating proposed release blockers	/jira:validate-blockers

JIRA Release Blocker Validator - Implementation Guide

This skill provides detailed implementation guidance for the /jira:validate-blockers command, which helps release managers make data-driven blocker approval/rejection decisions.

When to Use This Skill

This skill is invoked automatically when the /jira:validate-blockers command is executed. It provides step-by-step implementation details for:

Querying JIRA for proposed release blockers (Release Blocker = Proposed)
Scoring blockers against Red Hat OpenShift release blocker criteria
Generating APPROVE/REJECT/DISCUSS recommendations

Prerequisites

Jira MCP server must be configured (see plugin README)
MCP tools available: mcp__atlassian__jira_*
Read-only access to JIRA APIs (no credentials required for public Red Hat JIRA issues)
For single bug mode: bug must be accessible and exist

Detailed Implementation Steps

Phase 1: Parse Arguments

Parse command-line arguments:

Extract target version from $1 (optional, format: X.Y like "4.21")
Extract component filter from $2 (optional, supports comma-separated values)
Extract --bug flag value (optional, for single bug validation mode)

Project:

Hardcoded to "OCPBUGS" project

Validate inputs:

If neither --bug nor target-version is provided, error out with message: "Error: Either target-version or --bug must be provided. Usage: /jira:validate-blockers [target-version] [component-filter] [--bug issue-key]"
If target version provided, verify it matches pattern X.Y (e.g., "4.21", "4.22")
If component filter provided without target version and without --bug, error out

Phase 2: Build JQL Query for Proposed Blockers

Determine query mode:

Single bug mode (if --bug is provided):
- Skip JQL query construction
- Use mcp__atlassian__jira_get_issue to fetch the single bug
- Target version and component filter are ignored in this mode
- Proceed to analysis with single bug only
Version + component mode (if both target version and component are provided):
- Build JQL query for proposed blockers matching target version and component filter
- Continue with query construction below
Version only mode (if only target version provided):
- Build JQL query for all proposed blockers for the target version
- Continue with query construction below

Base JQL for proposed blockers:

project = OCPBUGS AND type = Bug AND "Release Blocker" = Proposed

IMPORTANT: Use "Release Blocker" = Proposed NOT cf[12319743]. The field ID customfield_12319743 is the Release Blocker field, but in JQL use the field name.

Version filter construction:

When target version is provided (e.g., "4.21"), expand to search for both X.Y and X.Y.0:

AND ("Target Version" in (4.21, 4.21.0) OR "Target Backport Versions" in (4.21, 4.21.0) OR affectedVersion in (4.21, 4.21.0))

Status exclusion filter:

Always exclude already-fixed bugs:

AND status not in (Closed, "Release Pending", Verified, ON_QA)

Component filter construction:

No component specified:

Query all components (no component filter in JQL)

Single component:

AND component = "{COMPONENT}"

Multiple components (comma-separated):

AND component IN ({COMPONENT_LIST})

Final JQL examples:

Version only (4.21):

project = OCPBUGS AND type = Bug AND "Release Blocker" = Proposed AND ("Target Version" in (4.21, 4.21.0) OR "Target Backport Versions" in (4.21, 4.21.0) OR affectedVersion in (4.21, 4.21.0)) AND status not in (Closed, "Release Pending", Verified, ON_QA)

Version + component (4.21, "Hypershift"):

project = OCPBUGS AND type = Bug AND "Release Blocker" = Proposed AND ("Target Version" in (4.21, 4.21.0) OR "Target Backport Versions" in (4.21, 4.21.0) OR affectedVersion in (4.21, 4.21.0)) AND status not in (Closed, "Release Pending", Verified, ON_QA) AND component = "Hypershift"

Version + multiple components (4.21, "Hypershift,CVO"):

project = OCPBUGS AND type = Bug AND "Release Blocker" = Proposed AND ("Target Version" in (4.21, 4.21.0) OR "Target Backport Versions" in (4.21, 4.21.0) OR affectedVersion in (4.21, 4.21.0)) AND status not in (Closed, "Release Pending", Verified, ON_QA) AND component IN ("Hypershift", "Cluster Version Operator")

Phase 3: Query Proposed Blockers

Use MCP tools to fetch proposed blockers:

For version/component mode, use mcp__atlassian__jira_search:

jql: The constructed JQL query from Phase 2
fields: "key,summary,priority,severity,status,assignee,created,updated,labels,components,description,reporter,customfield_12319743,customfield_12319940"
expand: "renderedFields" (to get comments for workaround analysis)
limit: 1000 (adjust based on expected results)

Parse the response to extract:

Total count of proposed blockers
List of bug objects with all required fields

Custom fields to include:

customfield_12319743 - Release Blocker status (should be "Proposed")
customfield_12319940 - Target Version

For single bug mode (--bug flag), use mcp__atlassian__jira_get_issue:

issue_key: The bug key provided by user
fields: Same fields as above plus custom fields
expand: "renderedFields"
comment_limit: 100 (need to check for workaround mentions)

Handle query results:

If total is 0, display message: "✅ No proposed blockers found" with filter summary
If total > 20, show progress indicator
Cache all bug data for analysis (avoid re-querying)

Phase 4: Analyze Each Proposed Blocker

Analyze each proposed blocker using Red Hat OpenShift release blocker criteria.

Red Hat OpenShift Release Blocker Criteria:

Based on the official OpenShift blocker definition, bugs should be approved as release blockers when they meet these criteria:

Automatic/Strong Blockers (Recommend APPROVE):

Component Readiness regressions (label: ComponentReadinessRegression) - even tech-preview jobs, unless covered by approved exceptions
Service Delivery blockers (label: ServiceDeliveryBlocker) - most bugs with this label are blockers
Data loss, service unavailability, or data corruption - most bugs in this category are blockers
Install/upgrade failures - may be blockers based on scope (all platforms vs specific form-factor)
Perception of failed upgrade - bugs that appear as upgrade failures to users
Regressions from previous release - most regressions are blockers (e.g., from Layered Product Testing)
Bugs severely impacting Service Delivery - regressions/bugs in default ROSA/OSD/ARO fleet features without acceptable workaround

Never Blockers (Recommend REJECT):

Severity below Important - no bugs with Low/Medium severity are blockers
New features without regressions - most new feature bugs are NOT blockers unless they regress existing functionality
CI-only issues - bugs that only affect CI infrastructure/jobs and don't impact product functionality are NOT release blockers
- Look for labels: ci-fail, ci-only, test-flake
- Check summary/description for keywords: "CI job", "test failure", "rehearsal", "periodic job", "e2e test"
- Check comments for explicit statements like "Won't affect the product", "CI-only", "infrastructure issue"
- Even if the bug describes install/upgrade failures, if it only manifests in CI environments, recommend REJECT

Workaround Assessment (may affect recommendation):

An acceptable workaround must meet ALL three criteria:

Idempotent - can be applied repeatedly without resulting change
Safe at scale - can be safely deployed to 1000's of clusters without material risk via automation
Timely - SD can implement before release is pushed to more Cincinnati channels (candidate, fast, stable)

If a workaround doesn't meet all three criteria, it's NOT an acceptable workaround.

For each proposed blocker:

Fetch bug details including summary, description, labels, priority, severity, comments
Check for CI-only indicators (REJECT criteria):
- Check labels: ci-fail, ci-only, test-flake
- Check summary/description for CI-specific keywords:
  - "CI job", "test failure", "rehearsal", "periodic job", "e2e test", "periodic-ci-"
- Check comments for explicit CI-only statements:
  - "Won't affect the product"
  - "CI-only"
  - "infrastructure issue"
  - "only affects CI"
- If CI-only indicators found, recommend REJECT regardless of severity or failure type
Analyze blocker criteria (if not CI-only):
- Check labels: ComponentReadinessRegression, ServiceDeliveryBlocker, UpgradeBlocker
- Check severity: Must be Important or higher (Critical/Urgent)
- Analyze summary/description for keywords:
  - Data loss, corruption, service unavailable
  - Install failure, upgrade failure
  - Regression
- Identify scope: All platforms vs specific form-factor/configuration
Check for acceptable workarounds:
- Use expand="renderedFields" to get comment text
- Search for keywords: "workaround", "work around", "alternative", "bypass"
- Assess if workaround meets all 3 criteria (idempotent, safe at scale, timely)
Generate recommendation:
- ✅ APPROVE - Meets automatic/strong blocker criteria, no acceptable workaround
- ❌ REJECT - CI-only issue, OR severity below Important, OR new feature without regression, OR has acceptable workaround
- ⚠️ DISCUSS - Edge cases requiring team discussion

Use MCP tools:

mcp__atlassian__jira_get_issue with expand="renderedFields" to get comments
Analyze comment text for workaround mentions

Phase 5: Generate Validation Report

Create comprehensive Markdown report with all blocker validation results.

Report Structure:

# 🚫 Release Blocker Validation Report
**Components**: {component list or "All"} | **Project**: OCPBUGS | **Proposed Blockers**: {count} | **Generated**: {timestamp}

## Summary
- ✅ **Recommend APPROVE**: X
- ❌ **Recommend REJECT**: Y
- ⚠️ **Needs DISCUSSION**: Z

---

## Blocker Analysis

### {BUG-KEY}: {Summary} {VERDICT}

**Recommendation**: {APPROVE/REJECT/DISCUSS} - {One-line justification}

**Criteria Matched**:
- {✅/❌} {Criterion name}
- {✅/❌} {Criterion name}
- ...

**Justification**:
{Detailed explanation of why this bug should or shouldn't be a blocker}

**Suggested Action**: {What to do next}

---

[Repeat for each proposed blocker]

---

## Next Steps
1. Review APPROVE recommendations - add to blocker list
2. Review REJECT recommendations - remove blocker status
3. Discuss unclear cases in triage meeting

Special case for single bug mode:

When --bug flag is used, adapt the report to focus on a single bug:

Summary shows single bug details (key, summary, verdict)
Analysis section shows detailed criteria analysis for this specific bug
Next Steps adapted for single bug action

Phase 6: Error Handling

Invalid issue ID (single bug mode):

Display error: "Could not find issue {issue-id}"
Verify issue ID is correct format
Check user has access to the issue

Invalid arguments:

Invalid component name: Warn but continue (JIRA will return no results)

No proposed blockers found:

Display success message: "✅ No proposed blockers found"
Show filter summary (components, project: OCPBUGS)
Confirm no blocker decisions needed

MCP tool errors:

If mcp__atlassian__jira_search fails, display JQL query and error message
If mcp__atlassian__jira_get_issue fails:
1. Fallback to WebFetch: Try fetching via https://issues.redhat.com/browse/{issue-key}
2. If WebFetch succeeds: Parse the web page to extract bug details (summary, severity, description) and continue with validation
3. If WebFetch also fails: Display clear error indicating bug doesn't exist or isn't accessible
Provide troubleshooting guidance (check MCP server, verify credentials)

Large result sets (>50 blockers):

Show progress indicators during analysis
Consider warning user: "Found {count} proposed blockers. This may take a moment to analyze."

Performance Considerations

Query optimization: Only fetch proposed blockers (cf[12319940] = "Proposed")
Component scoping: Use component filters to reduce result set size
Batch operations: Use mcp__atlassian__jira_search with appropriate limits (avoid pagination when possible)
Caching: Store bug data in memory during execution to avoid re-querying JIRA

JQL Query Examples