GitHub Issues Usage Guide:

[vvalderrv]

GitHub Issues Usage Guidelines

Introduction

GitHub Issues is an essential tool for managing development requests, tracking bugs, and coordinating the release process. This documentation outlines the standard practices for using GitHub Issues to manage tasks, bugs, and feature requests in a consistent and efficient manner. It is designed for developers and release managers to ensure smooth project tracking and communication.

Services Available

GitHub Issues supports a wide range of features to streamline issue tracking:

• Issue Creation: Create issues for tasks, bugs, features, or requests.
• Labels: Use labels to categorize and prioritize issues (e.g., bug, feature, high-priority).
• Assignees: Assign issues to developers or teams for ownership and resolution.
• Milestones: Group issues into milestones corresponding to specific project phases or releases.
• Projects: Organize issues using GitHub Projects for a visual representation of the workflow.
• Comments: Collaborate on issue resolution with inline discussions and updates.
• Linked Issues: Link related issues to track dependencies or cross-functional work.

How to Submit a Request

To create an issue for tracking a request:

1. Navigate to the Issues tab of the repository.
2. Click New issue to open the issue template.
3. In the title, provide a brief but clear description of the issue.
4. In the description field, provide details, including:
   • Type of issue (e.g., bug, feature request, task)
   • Expected vs. actual behavior (for bugs)
   • Detailed steps to reproduce (for bugs)
   • Specific requirements for features or enhancements
   • Any relevant context, links, or screenshots
5. Apply appropriate labels to categorize the issue (e.g., bug, enhancement, high-priority).
6. Assign the issue to relevant developers or teams.
7. If applicable, set a milestone to associate the issue with a specific release or project phase.
8. Submit the issue by clicking Submit new issue.

Managing and Tracking Issues

• Issue Discussion: Engage in discussions by commenting on issues. Ensure clarity in communication and document any changes to issue status.
• Status Updates: Use labels like in-progress, blocked, or ready-for-review to track the current status of the issue.
• Milestone Completion: Mark issues as complete when they are resolved and update the milestone to reflect progress toward the next release.

Escalation Process

If an issue is critical or has not been resolved within the expected timeframe:

1. Add a comment tagging the release manager or the relevant team lead to escalate attention.
2. If the issue is blocking progress or a release, mark it with the critical label and request urgent resolution.
3. In case of high-impact issues, escalate to a team meeting or backlog grooming session for prioritization.

---

GitHub Issues Workflow

The issue workflow defines how issues should be managed from creation to resolution. This ensures a consistent and efficient process for tracking and completing tasks, bugs, and feature requests. The following stages represent the general flow of issues within a project:

1. Issue Creation

• Initiation: Issues are created to report bugs, request features, or track tasks. When creating an issue, ensure that it is clear, concise, and includes enough context for resolution (e.g., steps to reproduce for bugs or acceptance criteria for features).
• Labeling: Immediately label the issue to categorize it (e.g., bug, feature, enhancement, documentation, high-priority) and apply any relevant tags for quick filtering.
• Assignment: Assign the issue to the appropriate developer(s) or team based on expertise and workload.

2. Prioritization

• Review: Issues are reviewed by the team lead or release manager to prioritize based on project goals, deadlines, and resources.
• Milestones: Issues that need to be addressed in an upcoming release are added to a milestone to align with specific release goals.
• Criticality: High-priority issues (e.g., critical bugs or blockers) should be flagged accordingly, either by assigning high-priority labels or marking them as blocked if dependent on other work.

3. Work in Progress

• Active Development: Once an issue is assigned, the responsible developer works on resolving it, implementing the required changes, or addressing the reported bug.
• In-Progress Status: Use labels like in-progress to signal that work has started. If the issue is blocked by another task, label it as blocked to indicate its dependency.
• Regular Updates: Developers should provide regular updates in the comments section to keep the team informed of progress, roadblocks, and required changes.

4. Review & Testing

• Peer Review: After development is completed, the issue enters the review stage. A peer or the designated reviewer verifies the fix or implementation.
• Testing: For bug fixes, run automated or manual tests to ensure the issue is resolved. For new features, verify that the feature works as expected and meets the initial requirements.
• Feedback Loop: If the issue requires additional work, comments are left for further refinement. Once the fix is verified, the issue can proceed to the final stage.

5. Resolution

• Completion: Once the issue is resolved and tested, it should be marked as closed and moved to the completed milestone. The relevant team members or release manager should verify that the issue is fully resolved and all criteria are met.
• Final Verification: Confirm that the issue’s resolution has been documented appropriately (e.g., release notes, change logs) before closing.
• Release Notes: For issues resolved in the release, include any important details in the release notes for transparency.

6. Post-Release Monitoring

• Reopen if Necessary: If the issue reappears or the fix doesn't work as expected, the issue can be reopened with additional context or debugging information.
• Continuous Improvement: Feedback from resolved issues should be used to improve workflows, development processes, and issue management practices for future releases.