637 lines
14 KiB
Markdown
637 lines
14 KiB
Markdown
# Jira Workflow Transitions Skill
|
|
|
|
Understanding and navigating Jira workflow states and transitions using jira-cli.
|
|
|
|
## Overview
|
|
|
|
Jira workflows define how issues move through different states from creation to completion. This skill helps you understand workflow concepts and effectively transition issues using jira-cli.
|
|
|
|
## Workflow Fundamentals
|
|
|
|
### What is a Workflow?
|
|
|
|
A workflow is a set of **statuses** and **transitions** that an issue moves through during its lifecycle.
|
|
|
|
**Status**: Current state of an issue (e.g., "To Do", "In Progress", "Done")
|
|
|
|
**Transition**: Action that moves an issue from one status to another (e.g., "Start Progress", "Resolve")
|
|
|
|
### Common Workflow Types
|
|
|
|
**1. Basic Workflow**
|
|
```
|
|
To Do → In Progress → Done
|
|
```
|
|
|
|
**2. Scrum Workflow**
|
|
```
|
|
Backlog → To Do → In Progress → In Review → Done → Closed
|
|
```
|
|
|
|
**3. Complex Workflow**
|
|
```
|
|
Open → In Progress → In Review → Testing → Blocked
|
|
↓
|
|
Done → Closed
|
|
```
|
|
|
|
## Standard Workflow States
|
|
|
|
### Initial States
|
|
|
|
**Backlog**
|
|
- Issues that might be worked on in future
|
|
- Not yet committed to a sprint
|
|
- May need grooming
|
|
|
|
**To Do**
|
|
- Ready to be worked on
|
|
- Accepted into sprint or ready for picking up
|
|
- All requirements clear
|
|
|
|
**Open**
|
|
- Newly created issue
|
|
- Needs triage or assignment
|
|
- May need more information
|
|
|
|
### Active Work States
|
|
|
|
**In Progress**
|
|
- Actively being worked on
|
|
- Assigned to someone
|
|
- Development underway
|
|
|
|
**In Review**
|
|
- Code/work completed
|
|
- Awaiting peer review or approval
|
|
- Pull request open
|
|
|
|
**Testing / QA**
|
|
- Under quality assurance testing
|
|
- Verification of acceptance criteria
|
|
- May be on staging environment
|
|
|
|
### Blocked States
|
|
|
|
**Blocked**
|
|
- Cannot proceed
|
|
- Waiting on external dependency
|
|
- Requires resolution of blocker
|
|
|
|
**Waiting for Info**
|
|
- Need clarification or additional details
|
|
- Awaiting stakeholder input
|
|
- Cannot proceed without information
|
|
|
|
### Completion States
|
|
|
|
**Done**
|
|
- Work completed
|
|
- Accepted by product owner
|
|
- Meets Definition of Done
|
|
|
|
**Closed**
|
|
- Fully resolved and closed
|
|
- No further action needed
|
|
- Archived state
|
|
|
|
**Resolved**
|
|
- Issue addressed
|
|
- May need verification
|
|
- Intermediate completion state
|
|
|
|
### Rejection States
|
|
|
|
**Won't Fix**
|
|
- Decision not to address
|
|
- Out of scope
|
|
- Not a priority
|
|
|
|
**Duplicate**
|
|
- Same as another issue
|
|
- Linked to original issue
|
|
- Closed as duplicate
|
|
|
|
**Cannot Reproduce**
|
|
- Bug cannot be reproduced
|
|
- Insufficient information
|
|
- May reopen if new info emerges
|
|
|
|
## Transitioning Issues
|
|
|
|
### Basic Transition
|
|
|
|
```bash
|
|
jira issue move PROJ-123
|
|
```
|
|
|
|
This opens an interactive menu showing available transitions.
|
|
|
|
### Direct Transition
|
|
|
|
```bash
|
|
jira issue move PROJ-123 "In Progress"
|
|
```
|
|
|
|
Moves directly to specified state if transition is available.
|
|
|
|
### Transition with Comment
|
|
|
|
```bash
|
|
jira issue move PROJ-123 "Done" --comment "Completed feature implementation. Ready for deployment."
|
|
```
|
|
|
|
Always add comments to provide context about the transition.
|
|
|
|
### Checking Available Transitions
|
|
|
|
```bash
|
|
jira issue view PROJ-123 --plain
|
|
```
|
|
|
|
Shows current status and available next states.
|
|
|
|
## Common Transition Patterns
|
|
|
|
### Starting Work
|
|
|
|
**From To Do to In Progress:**
|
|
```bash
|
|
# 1. Assign to yourself
|
|
jira issue assign PROJ-123 @me
|
|
|
|
# 2. Move to In Progress
|
|
jira issue move PROJ-123 "In Progress" --comment "Starting work on authentication feature"
|
|
```
|
|
|
|
### Submitting for Review
|
|
|
|
**From In Progress to In Review:**
|
|
```bash
|
|
jira issue move PROJ-123 "In Review" --comment "PR created: https://github.com/company/repo/pull/456"
|
|
```
|
|
|
|
### Handling Review Feedback
|
|
|
|
**From In Review back to In Progress:**
|
|
```bash
|
|
jira issue move PROJ-123 "In Progress" --comment "Addressing review feedback: refactoring auth logic"
|
|
```
|
|
|
|
### Completing Work
|
|
|
|
**From In Review to Done:**
|
|
```bash
|
|
jira issue move PROJ-123 "Done" --comment "PR merged. All acceptance criteria met."
|
|
```
|
|
|
|
### Handling Blockers
|
|
|
|
**From In Progress to Blocked:**
|
|
```bash
|
|
jira issue move PROJ-123 "Blocked" --comment "Waiting for API spec from backend team"
|
|
jira issue link PROJ-123 PROJ-100 "is blocked by"
|
|
```
|
|
|
|
**From Blocked back to In Progress:**
|
|
```bash
|
|
jira issue move PROJ-123 "In Progress" --comment "Blocker resolved. Resuming work."
|
|
```
|
|
|
|
### Closing Issues
|
|
|
|
**From Done to Closed:**
|
|
```bash
|
|
jira issue move PROJ-123 "Closed" --comment "Verified in production. No issues reported."
|
|
```
|
|
|
|
### Rejecting Issues
|
|
|
|
**Won't Fix:**
|
|
```bash
|
|
jira issue move PROJ-123 "Closed" --resolution "Won't Fix" --comment "Decision: Out of scope for current roadmap"
|
|
```
|
|
|
|
**Duplicate:**
|
|
```bash
|
|
jira issue link PROJ-123 PROJ-100 "duplicates"
|
|
jira issue move PROJ-123 "Closed" --resolution "Duplicate" --comment "Duplicate of PROJ-100"
|
|
```
|
|
|
|
**Cannot Reproduce:**
|
|
```bash
|
|
jira issue move PROJ-123 "Closed" --resolution "Cannot Reproduce" --comment "Unable to reproduce. Please reopen with more details if issue persists."
|
|
```
|
|
|
|
## Workflow Best Practices
|
|
|
|
### 1. Always Add Comments
|
|
|
|
❌ Bad:
|
|
```bash
|
|
jira issue move PROJ-123 "In Progress"
|
|
```
|
|
|
|
✅ Good:
|
|
```bash
|
|
jira issue move PROJ-123 "In Progress" --comment "Starting with database schema design"
|
|
```
|
|
|
|
### 2. Update Before Transitioning
|
|
|
|
```bash
|
|
# Update fields first
|
|
jira issue edit PROJ-123 --priority High
|
|
jira issue assign PROJ-123 @me
|
|
|
|
# Then transition
|
|
jira issue move PROJ-123 "In Progress"
|
|
```
|
|
|
|
### 3. Link Related Work
|
|
|
|
```bash
|
|
# When moving to review, link PR
|
|
jira issue move PROJ-123 "In Review" --comment "PR: https://github.com/company/repo/pull/456"
|
|
|
|
# When blocking, link blocker
|
|
jira issue move PROJ-123 "Blocked"
|
|
jira issue link PROJ-123 PROJ-100 "is blocked by"
|
|
```
|
|
|
|
### 4. Don't Skip States
|
|
|
|
❌ Bad (skipping review):
|
|
```bash
|
|
jira issue move PROJ-123 "Done" # Directly from In Progress
|
|
```
|
|
|
|
✅ Good (following workflow):
|
|
```bash
|
|
jira issue move PROJ-123 "In Review" # From In Progress
|
|
# ... review happens ...
|
|
jira issue move PROJ-123 "Done" # From In Review
|
|
```
|
|
|
|
### 5. Verify Before Completion
|
|
|
|
Before moving to Done:
|
|
```bash
|
|
# Review issue details
|
|
jira issue view PROJ-123 --plain
|
|
|
|
# Check acceptance criteria met
|
|
# Verify tests passing
|
|
# Confirm deployment successful
|
|
|
|
# Then complete
|
|
jira issue move PROJ-123 "Done" --comment "All acceptance criteria met. Deployed to production."
|
|
```
|
|
|
|
## Workflow States by Issue Type
|
|
|
|
### Bug Workflow
|
|
|
|
```
|
|
Open → In Progress → In Review → Testing → Fixed → Closed
|
|
↓
|
|
Cannot Reproduce
|
|
Won't Fix
|
|
```
|
|
|
|
**Key transitions:**
|
|
```bash
|
|
# Start fix
|
|
jira issue move BUG-123 "In Progress" --comment "Investigating root cause"
|
|
|
|
# Submit fix
|
|
jira issue move BUG-123 "In Review" --comment "Fix PR: ..."
|
|
|
|
# After QA
|
|
jira issue move BUG-123 "Fixed" --comment "Verified on staging"
|
|
|
|
# After deployment
|
|
jira issue move BUG-123 "Closed" --comment "Fix deployed to production"
|
|
```
|
|
|
|
### Story Workflow
|
|
|
|
```
|
|
Backlog → To Do → In Progress → In Review → Done → Closed
|
|
```
|
|
|
|
**Key transitions:**
|
|
```bash
|
|
# Sprint planning
|
|
jira issue move STORY-123 "To Do" --comment "Added to Sprint 42"
|
|
|
|
# Start development
|
|
jira issue move STORY-123 "In Progress"
|
|
|
|
# Code review
|
|
jira issue move STORY-123 "In Review" --comment "PR: ..."
|
|
|
|
# Accept story
|
|
jira issue move STORY-123 "Done" --comment "Demo approved by PO"
|
|
```
|
|
|
|
### Task Workflow
|
|
|
|
```
|
|
To Do → In Progress → Done
|
|
```
|
|
|
|
**Key transitions:**
|
|
```bash
|
|
# Simple workflow
|
|
jira issue move TASK-123 "In Progress"
|
|
# ... work ...
|
|
jira issue move TASK-123 "Done"
|
|
```
|
|
|
|
### Epic Workflow
|
|
|
|
```
|
|
To Do → In Progress → Done → Closed
|
|
```
|
|
|
|
**Epics transition when child stories complete:**
|
|
```bash
|
|
# Start epic when first story starts
|
|
jira issue move EPIC-100 "In Progress"
|
|
|
|
# Complete epic when all stories done
|
|
jira issue move EPIC-100 "Done" --comment "All stories completed. Feature fully implemented."
|
|
```
|
|
|
|
## Handling Special Cases
|
|
|
|
### Reopening Issues
|
|
|
|
**Reopen a closed issue:**
|
|
```bash
|
|
jira issue move PROJ-123 "Reopened" --comment "Bug has reoccurred. New reproduction steps: ..."
|
|
```
|
|
|
|
Or back to original state:
|
|
```bash
|
|
jira issue move PROJ-123 "In Progress" --comment "Reopening to address regression"
|
|
```
|
|
|
|
### Moving Between Sprints
|
|
|
|
```bash
|
|
# Issue incomplete at sprint end
|
|
jira issue move PROJ-123 "To Do" --comment "Moving to Sprint 43 due to blocker"
|
|
jira sprint add <NEXT_SPRINT_ID> PROJ-123
|
|
```
|
|
|
|
### Escalating Priority
|
|
|
|
```bash
|
|
# Change priority
|
|
jira issue edit PROJ-123 --priority Critical
|
|
|
|
# Add urgency label
|
|
jira issue edit PROJ-123 --label urgent
|
|
|
|
# Move up in workflow if needed
|
|
jira issue move PROJ-123 "In Progress" --comment "Escalated to critical. Addressing immediately."
|
|
```
|
|
|
|
### Split Issues
|
|
|
|
When an issue is too large:
|
|
```bash
|
|
# Create new issues
|
|
jira issue create --type Story --summary "Part 1: ..." --parent PROJ-123
|
|
jira issue create --type Story --summary "Part 2: ..." --parent PROJ-123
|
|
|
|
# Close original or mark as epic
|
|
jira issue edit PROJ-123 --type Epic
|
|
```
|
|
|
|
## Workflow Automation
|
|
|
|
### Git Integration
|
|
|
|
**Pre-commit hook:**
|
|
```bash
|
|
#!/bin/bash
|
|
# Ensure commits reference Jira issue
|
|
if ! git log -1 --pretty=%B | grep -qE "PROJ-[0-9]+"; then
|
|
echo "ERROR: Commit must reference Jira issue"
|
|
exit 1
|
|
fi
|
|
```
|
|
|
|
**Post-merge hook:**
|
|
```bash
|
|
#!/bin/bash
|
|
# Auto-transition after merge
|
|
ISSUE_KEY=$(git log -1 --pretty=%B | grep -oE "PROJ-[0-9]+")
|
|
if [ -n "$ISSUE_KEY" ]; then
|
|
jira issue move "$ISSUE_KEY" "Testing" --comment "Merged to main. Ready for QA."
|
|
fi
|
|
```
|
|
|
|
### CI/CD Integration
|
|
|
|
**On deployment:**
|
|
```bash
|
|
#!/bin/bash
|
|
# Extract issue keys from commits since last deploy
|
|
ISSUES=$(git log --pretty=%B $LAST_TAG..HEAD | grep -oE "PROJ-[0-9]+" | sort -u)
|
|
|
|
# Transition each issue
|
|
for issue in $ISSUES; do
|
|
jira issue move "$issue" "Testing" --comment "Deployed to staging by CI/CD pipeline"
|
|
done
|
|
```
|
|
|
|
### Scheduled Status Updates
|
|
|
|
**Daily reminder script:**
|
|
```bash
|
|
#!/bin/bash
|
|
# Find stale "In Progress" issues
|
|
jira issue list --jql "\
|
|
status = 'In Progress' AND \
|
|
updated <= -3d AND \
|
|
assignee = currentUser() \
|
|
" --plain
|
|
|
|
echo "Reminder: Update status on above issues"
|
|
```
|
|
|
|
## Troubleshooting Transitions
|
|
|
|
### Issue Won't Transition
|
|
|
|
**Problem:** Transition not available
|
|
|
|
**Solutions:**
|
|
1. Check current status
|
|
```bash
|
|
jira issue view PROJ-123 --plain
|
|
```
|
|
|
|
2. View available transitions
|
|
```bash
|
|
jira issue move PROJ-123 # Interactive mode shows options
|
|
```
|
|
|
|
3. Check required fields
|
|
- Some transitions require fields to be filled
|
|
- Use interactive mode to see requirements
|
|
|
|
4. Verify permissions
|
|
- You may not have permission for certain transitions
|
|
- Contact Jira admin if needed
|
|
|
|
### Missing Transition
|
|
|
|
**Problem:** Expected transition not showing
|
|
|
|
**Possible causes:**
|
|
- Workflow doesn't include that transition
|
|
- Conditional transition based on field values
|
|
- Permission restrictions
|
|
- Issue type has different workflow
|
|
|
|
**Solution:**
|
|
```bash
|
|
# Check what transitions are available
|
|
jira issue move PROJ-123
|
|
|
|
# Ask admin about workflow configuration
|
|
```
|
|
|
|
### Stuck in Status
|
|
|
|
**Problem:** Issue stuck in a status
|
|
|
|
**Solutions:**
|
|
1. Check for blockers
|
|
```bash
|
|
jira issue view PROJ-123 --plain
|
|
```
|
|
|
|
2. Add comment explaining situation
|
|
```bash
|
|
jira issue comment PROJ-123 "Stuck waiting for X. Escalating to Y."
|
|
```
|
|
|
|
3. Link blocking issues
|
|
```bash
|
|
jira issue link PROJ-123 PROJ-100 "is blocked by"
|
|
```
|
|
|
|
4. Move to Blocked status
|
|
```bash
|
|
jira issue move PROJ-123 "Blocked" --comment "Cannot proceed due to X"
|
|
```
|
|
|
|
### Accidental Transition
|
|
|
|
**Problem:** Moved to wrong status
|
|
|
|
**Solution:**
|
|
```bash
|
|
# Move back to correct status
|
|
jira issue move PROJ-123 "In Progress" --comment "Moved back to In Progress. Was accidentally marked as Done."
|
|
```
|
|
|
|
## Workflow Metrics
|
|
|
|
### Cycle Time
|
|
|
|
Time from "In Progress" to "Done":
|
|
```bash
|
|
# Issues completed this week
|
|
jira issue list --jql "\
|
|
status = Done AND \
|
|
resolved >= startOfWeek() \
|
|
" --raw
|
|
```
|
|
|
|
Calculate: `resolved_date - in_progress_date`
|
|
|
|
### Lead Time
|
|
|
|
Time from "To Do" to "Done":
|
|
```bash
|
|
# All resolved issues
|
|
jira issue list --jql "resolved >= startOfMonth()" --raw
|
|
```
|
|
|
|
Calculate: `resolved_date - created_date`
|
|
|
|
### Status Distribution
|
|
|
|
```bash
|
|
# Count issues by status
|
|
jira issue list --status "In Progress" --raw | grep -c key
|
|
jira issue list --status "In Review" --raw | grep -c key
|
|
jira issue list --status "Done" --raw | grep -c key
|
|
```
|
|
|
|
### Blocked Issue Tracking
|
|
|
|
```bash
|
|
# Currently blocked
|
|
jira issue list --status Blocked --plain
|
|
|
|
# How long blocked
|
|
jira issue list --jql "status = Blocked" --raw
|
|
```
|
|
|
|
## Custom Workflows
|
|
|
|
Organizations often customize workflows. To understand your workflow:
|
|
|
|
1. **View current issue state:**
|
|
```bash
|
|
jira issue view PROJ-123 --plain
|
|
```
|
|
|
|
2. **See available transitions:**
|
|
```bash
|
|
jira issue move PROJ-123 # Interactive mode
|
|
```
|
|
|
|
3. **Check workflow diagram:**
|
|
- Ask Jira admin for workflow documentation
|
|
- Or view in Jira UI: Project Settings → Workflows
|
|
|
|
4. **Document for team:**
|
|
Create a workflow guide specific to your project
|
|
|
|
## When to Use This Skill
|
|
|
|
- Learning Jira workflow concepts
|
|
- Transitioning issues appropriately
|
|
- Handling blocked or stuck issues
|
|
- Integrating workflows with git/CI/CD
|
|
- Troubleshooting transition issues
|
|
- Understanding team's specific workflow
|
|
|
|
## Best Practices Summary
|
|
|
|
1. **Always add meaningful comments** when transitioning
|
|
2. **Follow the workflow** - don't skip states
|
|
3. **Update issue details** before transitioning
|
|
4. **Link related work** (PRs, blockers, etc.)
|
|
5. **Use appropriate transitions** for issue type
|
|
6. **Verify completion** before marking Done
|
|
7. **Handle blockers explicitly** - don't leave hanging
|
|
8. **Document custom workflows** for team reference
|
|
|
|
## Next Steps
|
|
|
|
- Document your team's specific workflows
|
|
- Create scripts for common transition patterns
|
|
- Set up automation for workflow events
|
|
- Define clear Definition of Done for each state
|
|
- Establish team norms around transitions
|