1.2. Standards: Issue Description Guideline

GitHub Issue Best Practices: Writing Clear and Actionable Issues & Feature Requests

Why Issue Quality Matters

• Clear Communication: Well-written issues and feature requests ensure everyone understands the requirements and context within the project.
• Efficient Collaboration: Good documentation helps developers prioritize their efforts, leading to faster resolution times.
• Trackable Progress: Clearly defined issues and features make it easier to track progress and assess project status.

Core Principles for Effective Issues & Feature Requests

1. Problem or Opportunity-Focused: Describe the specific problem you're facing or the opportunity for enhancement. Be detailed and provide relevant context.
2. Concise and Actionable: Clearly state what needs to be fixed or implemented to address the problem/opportunity.

Issue Template (Recommended)

## Issue Title: <Short summary of the problem>

### Description:

**Problem:** <What's going wrong? Be specific.>

**Steps to Reproduce:** <If applicable, list the steps to recreate the issue.>

**Expected Behavior:** <Explain what should happen instead of the current behavior.>

**Actual Behavior:** <Describe what is currently happening.>

### Notes (Optional):
* <Any other helpful info, links, or screenshots>

Feature Request Template (Recommended):

## Feature Request: <Short summary of the feature>

### Description:

**Problem/Opportunity:** <Describe the user need or problem this feature solves/improves.>

**Proposed Solution:** <Explain your idea for the feature and how it addresses the problem/opportunity.>

### Acceptance Criteria: (Optional)

* <Specific condition 1>
* <Specific condition 2>
* ...

### Additional Notes (Optional):
* <Mockups, sketches, wireframes, etc.>

Examples of Good and Bad Feature Requests

Bad Feature Request	Good Feature Request
Title: "Add more stuff"	Title: "Add a "Dark Mode" toggle to the user interface"
Description: "We need more features."	Description: Many users have requested a dark mode option to reduce eye strain, especially during nighttime usage. This feature would improve accessibility and user experience.

Additional Tips

• Prioritize: Not all features can be implemented at once. Discuss and prioritize requests based on their impact and feasibility.
• Collaborate: Encourage feedback and discussion from the team and stakeholders to refine feature requests.
• Keep it Updated: As development progresses, update feature requests with new information or changes in scope.

Let's Write Better Issues and Feature Requests Together!

By following these guidelines, we can improve our communication and collaboration, leading to more focused development and successful project outcomes.

Questions? Feedback? Reach out to your team lead or project manager for assistance.