Skip to content

Issues, Labels, and Templates

Issues, Labels, and Templates

Overview

Issues are the fundamental unit of work: they track bugs, features, tasks, and questions. Labels, milestones, and templates standardize planning and make project triage and prioritization repeatable.

Best practices for issues

  • Write clear, descriptive titles (e.g., "Login button is unresponsive on Safari").
  • Provide steps to reproduce for bugs and expected vs actual behavior.
  • Add acceptance criteria (Given / When / Then) so 'done' is unambiguous.
  • Use labels for type, priority, and status to enable filtering.
  • Link PRs to issues using Fixes #123 to auto-close when merged.

Suggested label taxonomy

  • type: bug, feature, chore, docs, question
  • priority: p0-critical, p1-high, p2-medium, p3-low
  • status: needs-triage, in-progress, ready-for-review, blocked, done
  • area/component: auth, api, ui, db, etc.

Document chosen labels in CONTRIBUTING.md so the team uses them consistently.

Triage workflow

  1. New issues land in needs-triage.
  2. During triage, add type/priority, link to any related issues, and add to a milestone if appropriate.
  3. If unclear, ask for more info and move to needs-info or comment asking for clarification.
  4. Move to ready-for-dev when the issue is well-scoped and has acceptance criteria.

Templates (examples)

Bug report template (short):

**Title:**

**Steps to reproduce:**
1. 
2. 

**Expected behavior:**

**Actual behavior:**

**Environment (if applicable):**
- Browser / OS / Version

**Notes / Acceptance criteria:**
- Given ... When ... Then ...

Feature request template (short):

**Title:**

**Problem / motivation:**

**Proposed solution:**

**Acceptance criteria:**
- 

**Notes / alternatives considered:**

Milestones and releases

  • Use milestones to group issues for a sprint or release (e.g., "Sprint 3" or "v1.0").
  • Keep milestone scopes realistic and update them as priorities change.

Automation and integrations

  • Use issue templates in .github/ISSUE_TEMPLATE/ to present users with the correct form (bug vs feature).
  • Use GitHub Actions or other automation to apply labels based on keywords, link PRs to issues, or move issues between projects/boards.
  • Consider dependabot or security scanners for automated dependency and vulnerability tracking.

Practical tips

  • Keep issues actionable and small; split large work into smaller issues with clear sub-tasks.
  • Close stale issues or tag them as needs-info after a timeout.
  • Encourage contributors to use templates to provide consistent information.