Initial commit
This commit is contained in:
Zhongwei Li
464
commands/sng-issue.md
Normal file
464
commands/sng-issue.md
Normal file
@@ -0,0 +1,464 @@
|
||||
# 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?"
|
||||
Reference in New Issue
Block a user