1.2. Standards: Issue Description Guideline

GitHub Issue Best Practices: Writing Clear and Actionable Tasks/Bugs & 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 prioritise 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 Tasks/Bugs & 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.

Task/Bug Template (Recommended)

• GitHub Title: Task/Bug:<Short summary of the problem>
• Set the GitHub Issue Type: TASK or BUG
• Set the GitHub Label: e.g. Documentation, Enhancement, Bug
• Set the GitHub Project Field: Engineering Workflow Project Template

### Description:

**Problem:** <Clearly stating the problem upfront is crucial for understanding the issue..>

**Steps to Reproduce:** <If applicable, This is essential for bugs, allowing others to replicate the problem and verify solutions.>

**Expected Behaviour:** <Explain what should happen instead of the current behaviour.>

**Actual Behaviour:** <Describe what is currently happening, highlighting the discrepancy with the expected behaviour.>

### Notes (Optional):

* <Any other helpful info, environment, links, screenshots, Error messages, console logs, relevant code snippets>

Feature Request Template (Recommended):

• GitHub Issue Title: Feature: <Short summary of the problem>
• Set the GitHub Issue Type: FEATURE
• Set the GitHub Label: Documentation, Enhancement, Bug etc.
• Set the GitHub Project Field: Engineering Workflow Project Template

### 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

• Prioritise: Not all features can be implemented at once. Discuss and prioritise 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.