14 KiB
14 KiB
description, disable-model-invocation
| description | disable-model-invocation |
|---|---|
| Templates for creating well-structured GitHub issues for bugs, features, and tasks | 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.
## 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
## 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.
## 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
## 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.
## 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
## 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.
## 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:
# 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
- Choose the right template for the issue type
- Fill in all sections - don't leave blanks
- Be specific and actionable in descriptions
- Assign priority based on impact and urgency
- Add relevant labels beyond just priority
- Link related issues and PRs
- Include reproduction steps for bugs
- 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:
# 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
- Always use a template - ensures completeness
- Always assign priority - P1/P2/P3
- Be thorough - complete all sections
- Be specific - actionable details
- Think about the reader - they may have no context
Related Skills
- Use
github-issues-quick-referenceskill for gh CLI commands - Use
/gh-create-issuefor guided issue creation - Use
/gh-triagefor prioritizing existing issues