579 lines
14 KiB
Markdown
579 lines
14 KiB
Markdown
---
|
|
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
|