Initial commit
This commit is contained in:
Zhongwei Li
578
skills/issue-templates/SKILL.md
Normal file
578
skills/issue-templates/SKILL.md
Normal file
@@ -0,0 +1,578 @@
|
||||
---
|
||||
description: Templates for creating well-structured GitHub issues for bugs, features, and tasks
|
||||
disable-model-invocation: false
|
||||
---
|
||||
|
||||
# GitHub Issue Templates
|
||||
|
||||
Comprehensive templates for creating different types of GitHub issues. Use these templates to ensure consistency and completeness when creating issues.
|
||||
|
||||
---
|
||||
|
||||
## Bug Report Template
|
||||
|
||||
Use this template when reporting bugs, errors, or unexpected behavior.
|
||||
|
||||
```markdown
|
||||
## Description
|
||||
|
||||
Brief, clear description of the bug in 1-2 sentences.
|
||||
|
||||
## Steps to Reproduce
|
||||
|
||||
1. Go to [specific page or action]
|
||||
2. Click on [button/link]
|
||||
3. Enter [specific data]
|
||||
4. Observe the error
|
||||
|
||||
## Expected Behavior
|
||||
|
||||
What should happen when following the steps above.
|
||||
|
||||
## Actual Behavior
|
||||
|
||||
What actually happens. Include error messages, stack traces, or screenshots.
|
||||
|
||||
## Environment
|
||||
|
||||
- **Browser/OS**: Chrome 120 / macOS 14.2
|
||||
- **Version/Branch**: v2.1.0 / main
|
||||
- **Environment**: Production / Staging / Local
|
||||
|
||||
## Reproduction Rate
|
||||
|
||||
- [ ] Always (100%)
|
||||
- [ ] Frequently (>50%)
|
||||
- [ ] Sometimes (<50%)
|
||||
- [ ] Rare (<10%)
|
||||
|
||||
## Screenshots/Logs
|
||||
|
||||
[Attach screenshots, error logs, or console output if applicable]
|
||||
|
||||
## Additional Context
|
||||
|
||||
- When did this start happening?
|
||||
- Does it affect all users or specific users?
|
||||
- Any recent changes that might be related?
|
||||
- Workarounds discovered?
|
||||
|
||||
## Impact Assessment
|
||||
|
||||
- **Users Affected**: All / Subset / Single user
|
||||
- **Severity**: Critical / High / Medium / Low
|
||||
- **Business Impact**: [Describe impact on business operations]
|
||||
|
||||
## Suggested Priority
|
||||
|
||||
- [ ] P1 - Critical (blocks core functionality, affects all users)
|
||||
- [ ] P2 - High (significant impact but has workaround)
|
||||
- [ ] P3 - Normal (minor impact, can be scheduled)
|
||||
```
|
||||
|
||||
### Example Bug Report
|
||||
|
||||
```markdown
|
||||
## Description
|
||||
|
||||
Users cannot log in with SSO authentication, receiving "Invalid OAuth state" error.
|
||||
|
||||
## Steps to Reproduce
|
||||
|
||||
1. Navigate to https://app.example.com/login
|
||||
2. Click "Login with SSO"
|
||||
3. Enter corporate email
|
||||
4. Redirected to error page with "Invalid OAuth state"
|
||||
|
||||
## Expected Behavior
|
||||
|
||||
User should be authenticated and redirected to dashboard.
|
||||
|
||||
## Actual Behavior
|
||||
|
||||
Error page displays "Invalid OAuth state parameter" and user cannot proceed.
|
||||
|
||||
## Environment
|
||||
|
||||
- **Browser/OS**: All browsers / All OS
|
||||
- **Version/Branch**: v2.3.1 / production
|
||||
- **Environment**: Production
|
||||
|
||||
## Reproduction Rate
|
||||
|
||||
- [x] Always (100%)
|
||||
|
||||
## Screenshots/Logs
|
||||
|
||||
```
|
||||
Error: OAuth state mismatch
|
||||
at validateState (auth.js:45)
|
||||
at processCallback (oauth.js:123)
|
||||
```
|
||||
|
||||
## Additional Context
|
||||
|
||||
- Started after deployment at 2:00 PM UTC today
|
||||
- Affects ALL users attempting SSO login
|
||||
- Username/password login still works
|
||||
- Related to PR #123 which updated OAuth library
|
||||
|
||||
## Impact Assessment
|
||||
|
||||
- **Users Affected**: All SSO users (~80% of user base)
|
||||
- **Severity**: Critical
|
||||
- **Business Impact**: Users cannot access application, blocking all work
|
||||
|
||||
## Suggested Priority
|
||||
|
||||
- [x] P1 - Critical (blocks core functionality, affects all users)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Feature Request Template
|
||||
|
||||
Use this template when proposing new features or enhancements.
|
||||
|
||||
```markdown
|
||||
## Feature Description
|
||||
|
||||
Clear, concise description of the proposed feature in 1-2 sentences.
|
||||
|
||||
## Problem Statement
|
||||
|
||||
What problem does this feature solve? Who experiences this problem?
|
||||
|
||||
## Proposed Solution
|
||||
|
||||
Detailed description of how the feature should work:
|
||||
|
||||
- User interaction flow
|
||||
- UI/UX considerations
|
||||
- Technical approach (high-level)
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] User can [specific action]
|
||||
- [ ] System responds with [expected behavior]
|
||||
- [ ] Edge case [X] is handled properly
|
||||
- [ ] Feature works on [platforms/browsers]
|
||||
|
||||
## User Stories
|
||||
|
||||
**As a** [type of user]
|
||||
**I want** [goal/desire]
|
||||
**So that** [benefit/value]
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
What other approaches were considered and why were they rejected?
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Requires [feature/component]
|
||||
- Blocks [other feature]
|
||||
- Depends on [external service/library]
|
||||
|
||||
## Success Metrics
|
||||
|
||||
How will we measure if this feature is successful?
|
||||
|
||||
- [ ] [Metric 1]
|
||||
- [ ] [Metric 2]
|
||||
|
||||
## Priority Suggestion
|
||||
|
||||
- [ ] P1 - Critical (essential for launch/key business need)
|
||||
- [ ] P2 - High (important enhancement with clear value)
|
||||
- [ ] P3 - Normal (nice-to-have improvement)
|
||||
|
||||
## Additional Context
|
||||
|
||||
- Mockups or wireframes
|
||||
- User research or feedback
|
||||
- Competitive analysis
|
||||
- Technical considerations
|
||||
```
|
||||
|
||||
### Example Feature Request
|
||||
|
||||
```markdown
|
||||
## Feature Description
|
||||
|
||||
Add dark mode theme option to the application dashboard and user interface.
|
||||
|
||||
## Problem Statement
|
||||
|
||||
Users working in low-light environments or during evening hours find the bright interface uncomfortable and experience eye strain. Multiple users have requested a dark mode option in feedback surveys.
|
||||
|
||||
## Proposed Solution
|
||||
|
||||
Implement a theme toggle in user settings:
|
||||
|
||||
1. Add theme selector in user preferences (Settings > Appearance)
|
||||
2. Offer "Light", "Dark", and "Auto (system)" options
|
||||
3. Persist user preference to database
|
||||
4. Apply theme across all dashboard components
|
||||
5. Use CSS variables for easy theme switching
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] User can toggle between light and dark mode in settings
|
||||
- [ ] User can select "Auto" to follow system theme
|
||||
- [ ] Theme preference is saved per user account
|
||||
- [ ] Theme persists across sessions and devices
|
||||
- [ ] All dashboard components support both themes
|
||||
- [ ] Text remains readable in both themes (WCAG AA contrast)
|
||||
- [ ] Theme applies immediately without page refresh
|
||||
|
||||
## User Stories
|
||||
|
||||
**As a** dashboard user
|
||||
**I want** to switch to dark mode
|
||||
**So that** I can work comfortably in low-light environments without eye strain
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
1. **Single dark mode only**: Rejected - some users prefer light mode
|
||||
2. **Browser extension**: Rejected - requires external dependency
|
||||
3. **Time-based auto-switch**: Rejected - too complex for MVP
|
||||
|
||||
## Dependencies
|
||||
|
||||
- CSS variable system (already implemented)
|
||||
- User preferences API (needs enhancement)
|
||||
- Component library updates (all components must support theming)
|
||||
|
||||
## Success Metrics
|
||||
|
||||
- [ ] 30%+ of users enable dark mode within first month
|
||||
- [ ] Reduced complaints about interface brightness
|
||||
- [ ] Positive feedback in user surveys
|
||||
|
||||
## Priority Suggestion
|
||||
|
||||
- [ ] P1 - Critical
|
||||
- [x] P2 - High (frequently requested feature with clear user value)
|
||||
- [ ] P3 - Normal
|
||||
|
||||
## Additional Context
|
||||
|
||||
- Figma mockups: [link]
|
||||
- User survey results: 67% requested dark mode
|
||||
- Similar feature in competitor products
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task Template
|
||||
|
||||
Use this template for development tasks, technical work, or non-user-facing improvements.
|
||||
|
||||
```markdown
|
||||
## Objective
|
||||
|
||||
What needs to be accomplished? Be specific and actionable.
|
||||
|
||||
## Context
|
||||
|
||||
Why is this task needed? What's the background or motivation?
|
||||
|
||||
## Requirements
|
||||
|
||||
Detailed list of what must be completed:
|
||||
|
||||
- [ ] Requirement 1
|
||||
- [ ] Requirement 2
|
||||
- [ ] Requirement 3
|
||||
|
||||
## Technical Approach
|
||||
|
||||
High-level technical plan or considerations:
|
||||
|
||||
1. [Step or component 1]
|
||||
2. [Step or component 2]
|
||||
3. [Step or component 3]
|
||||
|
||||
## Files/Components Affected
|
||||
|
||||
- `path/to/file1.js`
|
||||
- `path/to/file2.py`
|
||||
- `component/Module`
|
||||
|
||||
## Testing Requirements
|
||||
|
||||
- [ ] Unit tests for [component]
|
||||
- [ ] Integration tests for [workflow]
|
||||
- [ ] Manual testing of [scenario]
|
||||
- [ ] Performance testing if applicable
|
||||
|
||||
## Documentation Requirements
|
||||
|
||||
- [ ] Update README
|
||||
- [ ] Update API docs
|
||||
- [ ] Add inline code comments
|
||||
- [ ] Update changelog
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Requires completion of #[issue-number]
|
||||
- Blocked by [external factor]
|
||||
- Depends on [library/service]
|
||||
|
||||
## Definition of Done
|
||||
|
||||
- [ ] Implementation complete and tested
|
||||
- [ ] Code reviewed and approved
|
||||
- [ ] Tests added and passing
|
||||
- [ ] Documentation updated
|
||||
- [ ] No regressions introduced
|
||||
- [ ] Deployed to staging/production
|
||||
|
||||
## Priority
|
||||
|
||||
- [ ] P1 - Critical (blocking other work)
|
||||
- [ ] P2 - High (important technical improvement)
|
||||
- [ ] P3 - Normal (standard development work)
|
||||
|
||||
## Estimated Effort
|
||||
|
||||
[Small / Medium / Large] or [hours/days estimate]
|
||||
```
|
||||
|
||||
### Example Task
|
||||
|
||||
```markdown
|
||||
## Objective
|
||||
|
||||
Refactor authentication middleware to support multiple OAuth providers (GitHub, Google, Microsoft).
|
||||
|
||||
## Context
|
||||
|
||||
Currently auth middleware only supports GitHub OAuth. New enterprise customers require Google and Microsoft SSO support. The existing implementation is tightly coupled to GitHub, making it difficult to extend.
|
||||
|
||||
## Requirements
|
||||
|
||||
- [ ] Abstract OAuth provider interface
|
||||
- [ ] Implement provider-specific adapters for GitHub, Google, Microsoft
|
||||
- [ ] Update configuration to support multiple providers
|
||||
- [ ] Maintain backward compatibility with existing GitHub auth
|
||||
- [ ] Add provider selection to login UI
|
||||
|
||||
## Technical Approach
|
||||
|
||||
1. Create `OAuthProvider` interface with standard methods
|
||||
2. Extract GitHub-specific code into `GitHubProvider` adapter
|
||||
3. Implement `GoogleProvider` and `MicrosoftProvider` adapters
|
||||
4. Update middleware to route to appropriate provider based on config
|
||||
5. Add provider selection dropdown to login page
|
||||
6. Update user model to store provider type
|
||||
|
||||
## Files/Components Affected
|
||||
|
||||
- `src/middleware/auth.js` - Main refactoring
|
||||
- `src/providers/github.js` - New file
|
||||
- `src/providers/google.js` - New file
|
||||
- `src/providers/microsoft.js` - New file
|
||||
- `src/config/oauth.js` - Configuration updates
|
||||
- `src/components/LoginForm.jsx` - UI updates
|
||||
- `src/models/User.js` - Schema updates
|
||||
|
||||
## Testing Requirements
|
||||
|
||||
- [ ] Unit tests for each provider adapter
|
||||
- [ ] Integration tests for full auth flow with each provider
|
||||
- [ ] Test backward compatibility with existing GitHub users
|
||||
- [ ] Test provider switching for users
|
||||
- [ ] Manual testing of UI provider selection
|
||||
|
||||
## Documentation Requirements
|
||||
|
||||
- [ ] Update README with OAuth configuration examples
|
||||
- [ ] Document provider interface in code
|
||||
- [ ] Add setup guide for each OAuth provider
|
||||
- [ ] Update environment variable documentation
|
||||
|
||||
## Dependencies
|
||||
|
||||
- OAuth credentials for Google and Microsoft (in progress)
|
||||
- No blocking dependencies
|
||||
|
||||
## Definition of Done
|
||||
|
||||
- [ ] All three providers implemented and tested
|
||||
- [ ] Existing GitHub auth continues to work
|
||||
- [ ] Tests added for all providers (100% coverage)
|
||||
- [ ] Code reviewed and approved
|
||||
- [ ] Documentation complete
|
||||
- [ ] Deployed to staging for QA testing
|
||||
- [ ] No performance regressions
|
||||
|
||||
## Priority
|
||||
|
||||
- [ ] P1 - Critical
|
||||
- [x] P2 - High (important for enterprise customer contracts)
|
||||
- [ ] P3 - Normal
|
||||
|
||||
## Estimated Effort
|
||||
|
||||
Large (3-5 days)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Documentation Update Template
|
||||
|
||||
Use this template for documentation improvements or additions.
|
||||
|
||||
```markdown
|
||||
## Documentation Need
|
||||
|
||||
What documentation is missing or needs improvement?
|
||||
|
||||
## Target Audience
|
||||
|
||||
Who will use this documentation?
|
||||
- [ ] End users
|
||||
- [ ] Developers
|
||||
- [ ] DevOps/Operations
|
||||
- [ ] Contributors
|
||||
|
||||
## Scope
|
||||
|
||||
What should be documented:
|
||||
|
||||
- [ ] Topic 1
|
||||
- [ ] Topic 2
|
||||
- [ ] Topic 3
|
||||
|
||||
## Existing Documentation
|
||||
|
||||
What documentation already exists that relates to this?
|
||||
|
||||
## Proposed Changes
|
||||
|
||||
What should be added, updated, or removed:
|
||||
|
||||
1. [Change 1]
|
||||
2. [Change 2]
|
||||
3. [Change 3]
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- [ ] Documentation is clear and accurate
|
||||
- [ ] Examples are provided
|
||||
- [ ] Common issues are addressed
|
||||
- [ ] Links are functional
|
||||
|
||||
## Priority
|
||||
|
||||
- [ ] P1 - Critical (blocking users/developers)
|
||||
- [ ] P2 - High (frequently needed info)
|
||||
- [ ] P3 - Normal (nice-to-have)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Command to Create Issue
|
||||
|
||||
Use these commands with the templates above:
|
||||
|
||||
```bash
|
||||
# Interactive issue creation (will prompt for all fields)
|
||||
gh issue create
|
||||
|
||||
# Create from template (save template to file first)
|
||||
gh issue create --body-file bug-report.md --title "Issue title" --label "P1,bug"
|
||||
|
||||
# Quick bug report
|
||||
gh issue create \
|
||||
--title "Brief bug description" \
|
||||
--body "$(cat <<'EOF'
|
||||
## Description
|
||||
[Bug description]
|
||||
|
||||
## Steps to Reproduce
|
||||
1. Step 1
|
||||
2. Step 2
|
||||
|
||||
## Expected vs Actual
|
||||
Expected: [...]
|
||||
Actual: [...]
|
||||
EOF
|
||||
)" \
|
||||
--label "P1,bug"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Template Selection Guide
|
||||
|
||||
| Issue Type | Template to Use | Labels to Add |
|
||||
|--------------------------|--------------------------|----------------------|
|
||||
| Bug or error | Bug Report | `bug`, `P1/P2/P3` |
|
||||
| New feature | Feature Request | `enhancement`, `P2/P3` |
|
||||
| Technical work | Task | `task`, `P2/P3` |
|
||||
| Performance issue | Bug Report | `bug`, `performance` |
|
||||
| Security vulnerability | Bug Report (urgent) | `security`, `P1` |
|
||||
| Documentation gap | Documentation Update | `documentation`, `P3` |
|
||||
| Refactoring | Task | `refactor`, `P3` |
|
||||
| Technical debt | Task | `tech-debt`, `P3` |
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### When Creating Issues
|
||||
|
||||
1. **Choose the right template** for the issue type
|
||||
2. **Fill in all sections** - don't leave blanks
|
||||
3. **Be specific and actionable** in descriptions
|
||||
4. **Assign priority** based on impact and urgency
|
||||
5. **Add relevant labels** beyond just priority
|
||||
6. **Link related issues** and PRs
|
||||
7. **Include reproduction steps** for bugs
|
||||
8. **Define acceptance criteria** for features
|
||||
|
||||
### Template Customization
|
||||
|
||||
These templates can be customized per repository:
|
||||
- Save templates to `.github/ISSUE_TEMPLATE/` directory
|
||||
- GitHub will show them in the issue creation UI
|
||||
- Customize sections based on team needs
|
||||
- Add repository-specific fields
|
||||
|
||||
---
|
||||
|
||||
## Using Templates with Guided Commands
|
||||
|
||||
The `/gh-create-issue` command will help you use these templates interactively:
|
||||
|
||||
```bash
|
||||
# Use guided workflow
|
||||
/gh-create-issue
|
||||
|
||||
# The command will:
|
||||
# 1. Ask for issue type (bug/feature/task)
|
||||
# 2. Load appropriate template
|
||||
# 3. Guide you through filling it out
|
||||
# 4. Create the issue with proper labels and priority
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Golden Rules
|
||||
|
||||
1. **Always use a template** - ensures completeness
|
||||
2. **Always assign priority** - P1/P2/P3
|
||||
3. **Be thorough** - complete all sections
|
||||
4. **Be specific** - actionable details
|
||||
5. **Think about the reader** - they may have no context
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- Use `github-issues-quick-reference` skill for gh CLI commands
|
||||
- Use `/gh-create-issue` for guided issue creation
|
||||
- Use `/gh-triage` for prioritizing existing issues
|
||||
Reference in New Issue
Block a user