Writing Good Issues

Writing Good Issues

An issue is a unit of work that someone else (or future-you) must be able to understand and act on without asking you questions.

Checklist for a well-formed issue

• Title - short, specific, starts with a verb: "Add issue templates", not "templates??"
• Description - what and why (context / motivation)
• Tasks - a checklist (- [ ]) breaking the work into steps; GitHub shows progress (e.g. 2 of 5)
• Acceptance criteria - how we know it is done
• Labels - one Type, one Priority, optional Effort / Area (see Issue Labels)
• Assignee - who owns it
• Links - related issues (#2), dependencies, references
• One issue = one thing. Split large work into several issues.

For bugs, also include: steps to reproduce, expected vs. actual behaviour, environment, screenshots/logs.

Template

## Description
What needs to be done and why.

## Tasks
- [ ] Step 1
- [ ] Step 2

## Acceptance criteria
- Observable condition that proves it's done.

## References / Depends on
- #12

Good vs. bad

❌ Bad	✅ Good
Title: "wiki"	Title: "Create wiki pages on Git version management"
Body: "do the wiki stuff"	Body: description, list of pages, acceptance criteria, depends on #2
no labels	Type: Documentation, Area: Wiki, Priority: Medium, Effort: Large

Linking issues and commits

• Mention an issue anywhere with #4 - GitHub cross-links both ways.
• Closes #4, Fixes #4 or Resolves #4 in a PR description or a commit on the default branch closes the issue automatically.
• Reference a commit by its SHA (e.g. a41c7e2) in a comment and GitHub turns it into a link.

Examples in this repo

See the open issues - each one follows this template.