259 lines
9.3 KiB
Markdown
259 lines
9.3 KiB
Markdown
---
|
|
name: OCPBUGS Jira Conventions
|
|
description: Jira conventions and bug templates for the OCPBUGS project
|
|
---
|
|
|
|
# OCPBUGS Jira Conventions
|
|
|
|
This skill provides conventions and requirements for creating bug reports in the OCPBUGS project, which is used by all OpenShift product teams for bug tracking.
|
|
|
|
## When to Use This Skill
|
|
|
|
Use this skill when creating bugs in the OCPBUGS project:
|
|
- **Project: OCPBUGS** - OpenShift Bugs
|
|
- **Issue Type: Bug** - Bug reports only
|
|
|
|
This skill is automatically invoked by the `/jira:create` command when the project_key is "OCPBUGS" or when issue type is "bug" without a project specified.
|
|
|
|
## Project Information
|
|
|
|
### OCPBUGS Project
|
|
**Full name:** OpenShift Bugs
|
|
|
|
**Key:** OCPBUGS
|
|
|
|
**Used for:** Bugs only
|
|
|
|
**Used by:** All OpenShift product teams
|
|
|
|
## Version Requirements
|
|
|
|
**Note:** Universal requirements (Security Level: Red Hat Employee, Labels: ai-generated-jira) are defined in the `/jira:create` command and automatically applied to all tickets.
|
|
|
|
### Affects Version/s (`versions`)
|
|
**Purpose:** Version where the bug was found
|
|
|
|
**Common values:** `4.19`, `4.20`, `4.21`, `4.22`, etc.
|
|
|
|
**Handling:**
|
|
- User should specify the version where they encountered the bug
|
|
- If not specified, prompt user: "Which version did you encounter this bug in?"
|
|
- Multiple versions can be specified if bug affects multiple releases
|
|
|
|
### Target Version (customfield_12319940)
|
|
**Purpose:** Version where the fix is targeted
|
|
|
|
**Common default:** `openshift-4.21` (or current development release)
|
|
|
|
**Override:** May be different based on:
|
|
- Severity (critical bugs may target earlier releases)
|
|
- Backport requirements
|
|
- Release schedule
|
|
|
|
**Never set:**
|
|
- Fix Version/s (`fixVersions`) - This is managed by the release team
|
|
|
|
### Version Override Handling
|
|
|
|
When user specifies a different version:
|
|
1. Accept the version as provided
|
|
2. Validate version exists using MCP tool `jira_get_project_versions` if needed
|
|
3. If version doesn't exist, suggest closest match or ask user to confirm
|
|
|
|
## Component Requirements
|
|
|
|
**IMPORTANT:** Component requirements are **team-specific**.
|
|
|
|
Some teams require specific components, while others do not. The OCPBUGS skill does NOT enforce component selection.
|
|
|
|
**Team-specific component handling:**
|
|
- Teams may have their own skills that define required components
|
|
- For example, HyperShift team uses `hypershift` skill for component selection
|
|
- Other teams may use different components based on their structure
|
|
|
|
**If component is not specified:**
|
|
- Prompt user: "Does this bug require a component? (optional)"
|
|
- If yes, ask user to specify component name
|
|
- If no, proceed without component
|
|
|
|
## Bug Description Template
|
|
|
|
**Note:** Bug template structure and sections are defined in the `create-bug` skill.
|
|
|
|
**OCPBUGS-specific:**
|
|
- All bugs must follow the bug template format
|
|
- Version-Release number field may differ from Affects Version (can be more specific)
|
|
|
|
**Note:** Security validation (credential scanning) is defined in the `/jira:create` command and automatically applied to all tickets.
|
|
|
|
## MCP Tool Integration
|
|
|
|
### For OCPBUGS Bugs
|
|
|
|
```python
|
|
mcp__atlassian__jira_create_issue(
|
|
project_key="OCPBUGS",
|
|
summary="<bug summary>",
|
|
issue_type="Bug",
|
|
description="<formatted bug template>",
|
|
components="<component name>", # if required by team
|
|
additional_fields={
|
|
"versions": [{"name": "4.21"}], # affects version (user-specified)
|
|
"customfield_12319940": "openshift-4.21", # target version (default or user-specified)
|
|
"labels": ["ai-generated-jira"],
|
|
"security": {"name": "Red Hat Employee"}
|
|
}
|
|
)
|
|
```
|
|
|
|
### Field Mapping Reference
|
|
|
|
| Requirement | MCP Parameter | Value |
|
|
|-------------|---------------|-------|
|
|
| Project | `project_key` | `"OCPBUGS"` |
|
|
| Issue Type | `issue_type` | `"Bug"` |
|
|
| Summary | `summary` | User-provided text |
|
|
| Description | `description` | Formatted bug template |
|
|
| Component | `components` | Team-specific (optional) |
|
|
| Affects Version | `additional_fields.versions` | `[{"name": "4.21"}]` (user-specified) |
|
|
| Target Version | `additional_fields.customfield_12319940` | `"openshift-4.21"` (default or user-specified) |
|
|
| Labels | `additional_fields.labels` | `["ai-generated-jira"]` (required) |
|
|
| Security Level | `additional_fields.security` | `{"name": "Red Hat Employee"}` (required) |
|
|
|
|
## Interactive Prompts
|
|
|
|
**Note:** Detailed bug template prompts are defined in the `create-bug` skill.
|
|
|
|
**OCPBUGS-specific prompts:**
|
|
- **Affects Version** (required): "Which version did you encounter this bug in?"
|
|
- Show common versions: 4.19, 4.20, 4.21, 4.22
|
|
- **Target Version** (optional): "Which version should this be fixed in? (default: openshift-4.21)"
|
|
- **Component** (if required by team): Defer to team-specific skills
|
|
|
|
## Examples
|
|
|
|
**Note:** All examples automatically apply universal requirements (Security: Red Hat Employee, Labels: ai-generated-jira) as defined in `/jira:create` command.
|
|
|
|
### Create Bug with Minimal Info
|
|
|
|
```bash
|
|
/jira:create bug "Control plane pods crash on upgrade from 4.20 to 4.21"
|
|
```
|
|
|
|
**OCPBUGS-specific defaults:**
|
|
- Project: OCPBUGS (default for bugs)
|
|
- Target Version: openshift-4.21 (default)
|
|
|
|
**Prompts:** See `create-bug` skill for bug template prompts, plus Affects Version
|
|
|
|
### Create Bug with Full Details
|
|
|
|
```bash
|
|
/jira:create bug OCPBUGS "API server returns 500 error when creating namespaces" --component "API" --version "4.21"
|
|
```
|
|
|
|
**OCPBUGS-specific defaults:**
|
|
- Affects Version: 4.21 (from --version flag)
|
|
- Target Version: openshift-4.21 (default)
|
|
- Component: API (from --component flag)
|
|
|
|
**Prompts:** See `create-bug` skill for bug template prompts
|
|
|
|
## Error Handling
|
|
|
|
### Invalid Version
|
|
|
|
**Scenario:** User specifies a version that doesn't exist.
|
|
|
|
**Action:**
|
|
1. Use `mcp__atlassian__jira_get_project_versions` to fetch available versions
|
|
2. Suggest closest match: "Version '4.21.5' not found. Did you mean '4.21.0'?"
|
|
3. Show available versions: "Available: 4.20.0, 4.21.0, 4.22.0"
|
|
4. Wait for confirmation or correction
|
|
|
|
### Component Required But Missing
|
|
|
|
**Scenario:** Team requires component, but user didn't specify.
|
|
|
|
**Action:**
|
|
1. If team skill detected required components, show options
|
|
2. Otherwise, generic prompt: "Does this bug require a component?"
|
|
3. If yes, ask user to specify component name
|
|
4. If no, proceed without component
|
|
|
|
### Sensitive Data Detected
|
|
|
|
**Scenario:** Credentials or secrets found in bug description or logs.
|
|
|
|
**Action:**
|
|
1. STOP issue creation immediately
|
|
2. Inform user: "I detected potential credentials in the bug report."
|
|
3. Show general location: "Found in: Additional info section"
|
|
4. Do NOT echo the sensitive data back
|
|
5. Suggest: "Please sanitize logs and use placeholder values like 'YOUR_API_KEY'"
|
|
6. Wait for user to provide sanitized content
|
|
|
|
### MCP Tool Failure
|
|
|
|
**Scenario:** MCP tool returns an error.
|
|
|
|
**Action:**
|
|
1. Parse error message for actionable information
|
|
2. Common errors:
|
|
- **"Field 'component' is required"** → Prompt for component (team-specific requirement)
|
|
- **"Permission denied"** → User may lack permissions to create bugs in OCPBUGS
|
|
- **"Version not found"** → Use version error handling above
|
|
3. Provide clear next steps
|
|
4. Offer to retry after corrections
|
|
|
|
### Wrong Issue Type
|
|
|
|
**Scenario:** User tries to create a story/task/epic in OCPBUGS.
|
|
|
|
**Action:**
|
|
1. Inform user: "OCPBUGS is for bugs only. Stories/Tasks/Epics should be created in CNTRLPLANE."
|
|
2. Suggest: "Would you like to create a bug instead, or change the project to CNTRLPLANE?"
|
|
3. Wait for user decision
|
|
|
|
**Note:** Jira description formatting (Wiki markup) is defined in the `/jira:create` command.
|
|
|
|
## Team-Specific Extensions
|
|
|
|
Teams using OCPBUGS may have additional team-specific requirements defined in separate skills:
|
|
|
|
- **HyperShift team:** Uses `hypershift` skill for component selection (HyperShift / ARO, HyperShift / ROSA, HyperShift)
|
|
- **Other teams:** May define their own skills with team-specific components and conventions
|
|
|
|
Team-specific skills are invoked automatically when team keywords are detected in the summary or when specific components are mentioned.
|
|
|
|
## Workflow Summary
|
|
|
|
When `/jira:create bug` is invoked:
|
|
|
|
1. ✅ **OCPBUGS skill loaded:** Applies project-specific conventions
|
|
2. ⚙️ **Apply OCPBUGS defaults:**
|
|
- Project: OCPBUGS (default for bugs)
|
|
- Target version: openshift-4.21 (default)
|
|
3. 🔍 **Check for team-specific skills:** If team keywords detected, invoke team skill (e.g., `hypershift`)
|
|
4. 💬 **Interactive prompts:**
|
|
- Affects version (required)
|
|
- Bug template sections (see `create-bug` skill)
|
|
- Component (if required by team)
|
|
|
|
**Note:** Universal requirements (security, labels), security validation, and issue creation handled by `/jira:create` command.
|
|
|
|
## Best Practices
|
|
|
|
1. **Version specificity:** Use exact versions (4.21.0) not just major versions (4.21) for Affects Version
|
|
2. **Template adherence:** Defer to `create-bug` skill for bug template best practices
|
|
3. **Link related issues:** Reference related bugs, PRs, or stories
|
|
|
|
**Note:** Universal best practices (security, credential sanitization, formatting) are defined in the `/jira:create` command.
|
|
|
|
## See Also
|
|
|
|
- `/jira:create` - Main command that invokes this skill
|
|
- `cntrlplane` skill - For CNTRLPLANE stories/epics/features/tasks
|
|
- Team-specific skills (e.g., `hypershift`) - For team-specific conventions
|
|
- `create-bug` skill - General bug report best practices
|