GitHub Projects and Issue Triage Guide

This guide provides a structured overview of how we use GitHub Projects to plan, prioritize, and track work in the pyicub project. It also outlines how to triage issues using standard labels, views, and processes.

---

1. Introduction to GitHub Projects

GitHub Projects is a planning and tracking system built directly into GitHub. It allows teams to manage tasks using issues, pull requests, labels, priorities, and milestones, all organized through interactive views.

GitHub Projects enables:

• Visual task tracking through boards and timelines.
• Issue categorization and prioritization.
• Assignment of tasks and ownership.
• Structured planning using milestones and fields.

---

2. Project Structure

Each project consists of:

• Items: Issues or pull requests that represent work.
• Views: Ways to visualize items (Boards, Tables, Roadmaps).
• Fields: Metadata like Status, Priority, Milestone, Assignee.
• Automation: Optional rules that move or modify items automatically.

---

3. Core Views and Their Purpose

View Name	Purpose
Status Board	Kanban-style flow for daily tracking of tasks.
Roadmap	Calendar-based timeline for long-term planning.
Prioritized Backlog	Sorted list of tasks by priority level.
Bugs	Shows only bug-labeled issues for QA and release prep.
My Items	Tasks assigned to the logged-in user.
In Review	Lists items currently under code review.

---

4. Field Definitions

Field	Purpose
Status	Tracks task progression (Backlog, Ready, In Progress, etc.).
Priority	Denotes urgency (P0, P1, P2).
Assignee	Who is responsible for completing the item.
Milestone	Targeted sprint, release, or date.
Estimate	Optional time or effort estimate.

---

5. Label Definitions

Label	Description
bug	A confirmed malfunction or incorrect behavior.
documentation	Missing, unclear, or incorrect documentation.
duplicate	Already tracked by another issue or PR.
enhancement	A feature request or usability improvement.
good first issue	Entry-level task suitable for new contributors.
help wanted	Maintainers welcome external contributions.
invalid	Not valid; caused by incorrect usage.
question	User or contributor request for clarification.
wontfix	Acknowledged but not planned for resolution.

---

6. Triage Process

Triage ensures that issues are categorized, prioritized, and actionable. This is typically done by maintainers on a weekly basis.

Step-by-step Workflow:

1. Confirm It’s an Issue

   • If it’s a question, label as question.
   • If it lacks enough context, label as invalid or request clarification.

2. Check for Duplicates

   • Search the Issues tab.
   • Close duplicates and link the existing issue.

3. Label and Categorize

   • Apply one or more labels (bug, enhancement, etc.).

4. Assign Priority

   • P0 = urgent/blocker
   • P1 = high-priority, next sprint
   • P2 = low-priority, backlog

5. Assign and Schedule

   • Assign a team member.
   • Associate the issue with a milestone.

6. Move in Status Board

   • Backlog: untriaged or new issues.
   • Ready: approved for development.
   • In Progress: active work.
   • In Review: under pull request.
   • Done: resolved/merged.

---

7. When to Close Issues

An issue can be closed if:

• The pull request linked to it is merged.
• It is determined to be invalid or a duplicate.
• It is accepted as wontfix.

---

8. Milestones and Roadmap Planning

Milestones group related issues and features under a release goal or sprint cycle. These are reflected visually in the Roadmap view. Each accepted issue should be attached to a milestone.

---

9. Best Practices

• Perform triage weekly.
• Ensure each task has a defined scope, priority, and assignee.
• Align Roadmap view with actual sprint or delivery timelines.
• Review and update issue status regularly.
• Ensure all code changes are linked to issues.

---