Issues, labels and team collaboration
↑Good issue tracking provides enough context to know what is wrong or missing, how success will be judged and who is responsible. It should not become a substitute for discussing architecture and reviewing code. GitHub issues hold the conversation and links to changes; GitHub Projects can present those issues across different plans and views.
Write actionable issues
Section titled “Write actionable issues”A useful issue title describes an outcome, such as Inventory items duplicate after reconnect, not merely Inventory. Include reproduction steps, actual and expected behavior, environment, severity, acceptance criteria and relevant logs or screenshots. Remove secrets, access tokens and personal information before sharing logs.
For feature work, define a small scope with a testable result. If one issue takes many weeks, split it into sub-issues that can each be implemented and reviewed. A Markdown checklist works well for small checkable steps inside a single issue; it isn’t a replacement for distinct tracked issues with assignees and review history.
Labels, milestones and project fields
Section titled “Labels, milestones and project fields”| Tool | Use it for | Example |
|---|---|---|
| Label | Categorizing across issues | bug, documentation, needs-repro |
| Milestone | A release or group of related work | v1.3 |
| Assignee | The person currently accountable | @reviewer |
| Sub-issue | A separately trackable component | Build inventory UI |
| Project field | Planning dimensions across a board | Status or Priority |
Define a compact label vocabulary; if everything is labeled urgent, the label does not help. Where GitHub offers issue types or organization issue fields, explain their difference from project fields before adding both.
Communicate through Markdown
Section titled “Communicate through Markdown”Use headings, lists, code fences, tables, links and task checkboxes to make complex discussions readable. Mentions notify people where permissions permit; use them thoughtfully. On GitHub, cross-references such as #42 can connect related issues and pull requests, and closing keywords in a pull request description may close the associated issue after the PR is merged to the default branch.
Repository issue templates or issue forms help gather predictable information. PR templates can remind authors to state tests, deployment risk and rollback options. A template is a prompt, not a substitute for substantive explanations.
Team access and review boundaries
Section titled “Team access and review boundaries”Grant repository access according to roles and least privilege; protect important branches with hosting-level rules. Separate project membership from repository permissions. Use reviews to challenge code, not people, and preserve decision rationale in the issue or PR rather than a private chat only.
A healthy collaboration loop is triage → assign → branch → implement → review → test → release → close or follow up. For an entire example, see issue to release.
Reference: GitHub issues, GitHub Projects.