GitHub Issue Templates

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

---

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:

# 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