465 lines
10 KiB
Markdown
465 lines
10 KiB
Markdown
# GitHub Issue Management Command
|
|
|
|
You are helping the user create, update, and manage GitHub issues following Sngular's project management best practices.
|
|
|
|
## Instructions
|
|
|
|
1. **Determine the action**:
|
|
- Create a new issue
|
|
- Update an existing issue
|
|
- Close an issue
|
|
- List issues with filters
|
|
- Link related issues
|
|
- Bulk operations on issues
|
|
|
|
2. **Verify GitHub repository**:
|
|
- Check if in a git repository
|
|
- Verify GitHub remote is configured
|
|
- Confirm user has `gh` CLI installed and authenticated
|
|
|
|
3. **Gather issue details**:
|
|
- Title (clear, concise, action-oriented)
|
|
- Description (problem statement, context, impact)
|
|
- Labels (type, priority, component, status)
|
|
- Assignees (who should work on this)
|
|
- Milestone (which release or sprint)
|
|
- Projects (which project board)
|
|
|
|
## Issue Creation
|
|
|
|
### Issue Template Structure
|
|
|
|
```markdown
|
|
## Problem Statement
|
|
Clear description of the issue, bug, or feature request.
|
|
|
|
## Current Behavior
|
|
What is happening now? (for bugs)
|
|
|
|
## Expected Behavior
|
|
What should happen instead?
|
|
|
|
## Steps to Reproduce
|
|
(For bugs)
|
|
1. Step 1
|
|
2. Step 2
|
|
3. Step 3
|
|
|
|
## Proposed Solution
|
|
(For features)
|
|
High-level approach to implementing this feature.
|
|
|
|
## Acceptance Criteria
|
|
- [ ] Criterion 1
|
|
- [ ] Criterion 2
|
|
- [ ] Criterion 3
|
|
|
|
## Technical Details
|
|
- Affected components:
|
|
- Dependencies:
|
|
- Estimated effort:
|
|
|
|
## Additional Context
|
|
Screenshots, logs, or relevant information.
|
|
|
|
## Related Issues
|
|
- Relates to #123
|
|
- Blocks #456
|
|
- Blocked by #789
|
|
```
|
|
|
|
### Issue Types & Labels
|
|
|
|
**Type Labels**:
|
|
- `bug` - Something isn't working
|
|
- `feature` - New feature or enhancement
|
|
- `documentation` - Documentation improvements
|
|
- `refactor` - Code refactoring
|
|
- `performance` - Performance improvements
|
|
- `security` - Security-related issues
|
|
- `tech-debt` - Technical debt
|
|
|
|
**Priority Labels**:
|
|
- `priority: critical` - Urgent, blocking work
|
|
- `priority: high` - Important, should be done soon
|
|
- `priority: medium` - Normal priority
|
|
- `priority: low` - Nice to have
|
|
|
|
**Status Labels**:
|
|
- `status: triage` - Needs initial review
|
|
- `status: ready` - Ready for development
|
|
- `status: in-progress` - Currently being worked on
|
|
- `status: review` - In code review
|
|
- `status: blocked` - Blocked by dependencies
|
|
- `status: on-hold` - Paused temporarily
|
|
|
|
**Component Labels**:
|
|
- `frontend` - UI/UX related
|
|
- `backend` - Server-side code
|
|
- `database` - Database changes
|
|
- `devops` - Infrastructure/deployment
|
|
- `api` - API changes
|
|
|
|
## GitHub CLI Commands
|
|
|
|
### Creating Issues
|
|
|
|
```bash
|
|
# Create basic issue
|
|
gh issue create --title "Issue title" --body "Issue description"
|
|
|
|
# Create issue with labels and assignee
|
|
gh issue create \
|
|
--title "Add user authentication" \
|
|
--body "$(cat issue-template.md)" \
|
|
--label "feature,backend,priority: high" \
|
|
--assignee username
|
|
|
|
# Create issue with milestone
|
|
gh issue create \
|
|
--title "Fix login bug" \
|
|
--body "Description" \
|
|
--label "bug,priority: critical" \
|
|
--milestone "Sprint 24"
|
|
|
|
# Create issue and assign to project
|
|
gh issue create \
|
|
--title "Implement dashboard" \
|
|
--body "Description" \
|
|
--label "feature" \
|
|
--project "Q4 Roadmap"
|
|
|
|
# Interactive issue creation
|
|
gh issue create
|
|
```
|
|
|
|
### Viewing Issues
|
|
|
|
```bash
|
|
# List all open issues
|
|
gh issue list
|
|
|
|
# List issues with specific label
|
|
gh issue list --label "bug"
|
|
|
|
# List issues assigned to user
|
|
gh issue list --assignee @me
|
|
|
|
# List issues in specific state
|
|
gh issue list --state closed
|
|
|
|
# List with custom columns
|
|
gh issue list --json number,title,labels,state
|
|
|
|
# View specific issue
|
|
gh issue view 123
|
|
|
|
# View issue in browser
|
|
gh issue view 123 --web
|
|
```
|
|
|
|
### Updating Issues
|
|
|
|
```bash
|
|
# Edit issue title
|
|
gh issue edit 123 --title "New title"
|
|
|
|
# Add labels
|
|
gh issue edit 123 --add-label "bug,priority: high"
|
|
|
|
# Remove labels
|
|
gh issue edit 123 --remove-label "priority: low"
|
|
|
|
# Add assignee
|
|
gh issue edit 123 --add-assignee username
|
|
|
|
# Remove assignee
|
|
gh issue edit 123 --remove-assignee username
|
|
|
|
# Set milestone
|
|
gh issue edit 123 --milestone "v2.0"
|
|
|
|
# Update body
|
|
gh issue edit 123 --body "New description"
|
|
|
|
# Add comment
|
|
gh issue comment 123 --body "This is a comment"
|
|
|
|
# Close issue
|
|
gh issue close 123
|
|
|
|
# Close with comment
|
|
gh issue close 123 --comment "Fixed in PR #456"
|
|
|
|
# Reopen issue
|
|
gh issue reopen 123
|
|
```
|
|
|
|
### Linking Issues
|
|
|
|
```bash
|
|
# Reference in comment
|
|
gh issue comment 123 --body "Related to #456"
|
|
|
|
# Link as blocking
|
|
gh issue comment 123 --body "Blocks #456"
|
|
|
|
# Link as blocked by
|
|
gh issue comment 123 --body "Blocked by #789"
|
|
|
|
# Link to PR
|
|
gh issue comment 123 --body "Fixed in PR #100"
|
|
```
|
|
|
|
### Bulk Operations
|
|
|
|
```bash
|
|
# Close multiple issues
|
|
gh issue list --label "wontfix" --json number --jq '.[].number' | \
|
|
xargs -I {} gh issue close {}
|
|
|
|
# Add label to multiple issues
|
|
gh issue list --search "authentication" --json number --jq '.[].number' | \
|
|
xargs -I {} gh issue edit {} --add-label "security"
|
|
|
|
# Assign all unassigned bugs
|
|
gh issue list --label "bug" --json number,assignees --jq '.[] | select(.assignees | length == 0) | .number' | \
|
|
xargs -I {} gh issue edit {} --add-assignee username
|
|
```
|
|
|
|
## Issue Templates
|
|
|
|
### Bug Report Template
|
|
|
|
```markdown
|
|
## Bug Description
|
|
Brief description of the bug.
|
|
|
|
## Environment
|
|
- OS: [e.g., macOS 14.0]
|
|
- Browser: [e.g., Chrome 120]
|
|
- Version: [e.g., 2.0.1]
|
|
|
|
## Steps to Reproduce
|
|
1. Go to '...'
|
|
2. Click on '...'
|
|
3. Scroll down to '...'
|
|
4. See error
|
|
|
|
## Expected Behavior
|
|
What you expected to happen.
|
|
|
|
## Actual Behavior
|
|
What actually happened.
|
|
|
|
## Screenshots/Logs
|
|
If applicable, add screenshots or logs.
|
|
|
|
## Possible Solution
|
|
(Optional) Suggest a fix or reason for the bug.
|
|
|
|
## Additional Context
|
|
Any other context about the problem.
|
|
```
|
|
|
|
### Feature Request Template
|
|
|
|
```markdown
|
|
## Feature Description
|
|
Clear description of the feature you'd like to see.
|
|
|
|
## Problem Statement
|
|
What problem does this feature solve?
|
|
|
|
## Proposed Solution
|
|
How should this feature work?
|
|
|
|
## Alternatives Considered
|
|
What other approaches did you consider?
|
|
|
|
## User Stories
|
|
- As a [user type], I want to [action], so that [benefit]
|
|
|
|
## Acceptance Criteria
|
|
- [ ] Criterion 1
|
|
- [ ] Criterion 2
|
|
|
|
## Technical Considerations
|
|
- Dependencies:
|
|
- Performance impact:
|
|
- Security implications:
|
|
- Breaking changes:
|
|
|
|
## Priority & Impact
|
|
- Priority: [High/Medium/Low]
|
|
- User impact: [High/Medium/Low]
|
|
- Implementation effort: [Large/Medium/Small]
|
|
```
|
|
|
|
## Best Practices
|
|
|
|
### Writing Good Issue Titles
|
|
|
|
✅ **Good**:
|
|
- "Add CSV export for user data"
|
|
- "Fix pagination bug on dashboard"
|
|
- "Improve API response time for /users endpoint"
|
|
- "Update authentication flow to support OAuth"
|
|
|
|
❌ **Bad**:
|
|
- "Bug" (not descriptive)
|
|
- "Feature request" (too vague)
|
|
- "This doesn't work" (no context)
|
|
- "URGENT FIX ASAP!!!" (not professional)
|
|
|
|
### Title Format
|
|
- **Bugs**: "Fix [issue] in [component]"
|
|
- **Features**: "Add [feature] to [component]"
|
|
- **Improvements**: "Improve [aspect] of [component]"
|
|
- **Refactoring**: "Refactor [component] to [goal]"
|
|
|
|
### Writing Good Descriptions
|
|
|
|
1. **Be specific**: Include exact error messages, versions, conditions
|
|
2. **Provide context**: Explain why this matters, who it affects
|
|
3. **Include steps**: For bugs, clear reproduction steps
|
|
4. **Add visuals**: Screenshots, diagrams, recordings when helpful
|
|
5. **Link related work**: Reference related issues, PRs, docs
|
|
6. **Set expectations**: Clarify scope, acceptance criteria
|
|
|
|
### Label Strategy
|
|
|
|
- Use consistent label taxonomy across the project
|
|
- Limit to 3-5 labels per issue for clarity
|
|
- Always include: type, priority, and component labels
|
|
- Use status labels to track progress
|
|
- Create custom labels for recurring themes
|
|
|
|
### Assigning Issues
|
|
|
|
- Assign when someone actively works on it
|
|
- Don't assign too far in advance
|
|
- One primary assignee, others as collaborators
|
|
- Unassign if work is paused or blocked
|
|
|
|
## Workflow Examples
|
|
|
|
### Example 1: Create Bug Report
|
|
|
|
```bash
|
|
# User reports: "Login page is broken on mobile"
|
|
|
|
gh issue create \
|
|
--title "Fix login page layout on mobile devices" \
|
|
--body "$(cat <<'EOF'
|
|
## Bug Description
|
|
The login form is not responsive on mobile devices below 768px width.
|
|
|
|
## Environment
|
|
- Device: iPhone 14
|
|
- OS: iOS 17.0
|
|
- Browser: Safari
|
|
|
|
## Steps to Reproduce
|
|
1. Open application on mobile device
|
|
2. Navigate to /login
|
|
3. Observe layout issues
|
|
|
|
## Expected Behavior
|
|
Login form should be centered and fully visible on mobile.
|
|
|
|
## Actual Behavior
|
|
Form elements overflow screen, submit button is cut off.
|
|
|
|
## Screenshots
|
|
[Attach screenshots]
|
|
|
|
## Acceptance Criteria
|
|
- [ ] Form is responsive on screens < 768px
|
|
- [ ] All elements visible without scrolling
|
|
- [ ] Touch targets are at least 44x44px
|
|
- [ ] Tested on iOS Safari and Android Chrome
|
|
EOF
|
|
)" \
|
|
--label "bug,frontend,priority: high" \
|
|
--assignee frontend-team
|
|
```
|
|
|
|
### Example 2: Feature Request with Requirements
|
|
|
|
```bash
|
|
gh issue create \
|
|
--title "Add user profile settings page" \
|
|
--body "$(cat ./docs/requirements/user-profile.md)" \
|
|
--label "feature,frontend,backend" \
|
|
--milestone "v2.0" \
|
|
--project "Q4 Features"
|
|
```
|
|
|
|
### Example 3: Link Related Issues
|
|
|
|
```bash
|
|
# This PR fixes issue #123 and is related to #124
|
|
gh issue comment 123 --body "Fixed in PR #200"
|
|
gh issue close 123
|
|
gh issue comment 124 --body "Implementation approach discussed in #123"
|
|
```
|
|
|
|
### Example 4: Triage Issues
|
|
|
|
```bash
|
|
# Review new issues
|
|
gh issue list --label "status: triage"
|
|
|
|
# Add priority and status
|
|
gh issue edit 123 --add-label "priority: high,status: ready" --remove-label "status: triage"
|
|
|
|
# Assign to team member
|
|
gh issue edit 123 --add-assignee developer1
|
|
```
|
|
|
|
## Integration with Project Boards
|
|
|
|
```bash
|
|
# List projects
|
|
gh project list
|
|
|
|
# View project
|
|
gh project view 1
|
|
|
|
# Add issue to project
|
|
gh project item-add 1 --url https://github.com/owner/repo/issues/123
|
|
|
|
# Move issue on board
|
|
gh project item-edit --project-id 1 --id ITEM_ID --field-id STATUS_FIELD_ID --value "In Progress"
|
|
```
|
|
|
|
## Advanced Filtering
|
|
|
|
```bash
|
|
# Issues created in last week
|
|
gh issue list --search "created:>=$(date -v-7d +%Y-%m-%d)"
|
|
|
|
# High priority unassigned bugs
|
|
gh issue list --label "bug,priority: high" --search "no:assignee"
|
|
|
|
# Issues mentioning "authentication"
|
|
gh issue list --search "authentication in:title,body"
|
|
|
|
# Issues assigned to me that are in progress
|
|
gh issue list --assignee @me --label "status: in-progress"
|
|
```
|
|
|
|
## Questions to Ask
|
|
|
|
Before creating or updating an issue:
|
|
1. "What type of issue is this? (bug, feature, improvement)"
|
|
2. "What is the clear, actionable title?"
|
|
3. "Do you have specific details like steps to reproduce or requirements?"
|
|
4. "What priority should this have?"
|
|
5. "Should this be assigned to anyone?"
|
|
6. "Should this be added to a milestone or project?"
|
|
7. "Are there related issues we should link to?"
|
|
|
|
Ask the user: "What would you like to do with GitHub issues?"
|