Writing an Issue Somebody Can Act On

An issue is a numbered thread attached to a repository. It has a title, a body, comments, a set of labels, and exactly one bit of state: open or closed.

That is deliberately minimal. GitHub Issues is not a project management tool with statuses and workflows and estimates; it is a discussion with a checkbox. Everything else — the board, the sprint, the priority — is built on top with labels and Projects.

Issues are not only bugs. On a healthy repository they are used for at least four things, and conflating them is the first thing labels fix.

The maintainer reading this has never seen your screen, does not have your data, and is probably doing this on a Sunday. Four things turn an issue from a burden into something somebody can pick up.

Two habits that cost nothing and help enormously. Search before opening — including closed issues, because the answer is frequently in one that was closed last year. And one issue per issue: a report containing three unrelated bugs cannot be closed until all three are fixed, so it stays open for months.

## Steps to reproduce1. Add a contact with the company `Acme, Inc.`2. Contacts → Export → CSV **Expected:** a file with all 40 contacts**Actual:** a 0-byte file <details><summary>Full stack trace</summary> ```TypeError: Cannot read properties of undefined (reading 'split')    at formatRow (src/export.ts:88:24)``` </details> - [ ] Reproduced on 2.4.1- [ ] Reproduced on main

The details block collapses a long stack trace so the issue stays readable, and the square-bracket list renders as real checkboxes anybody with write access can tick.

Three orthogonal ways to organise, and using them for the wrong axis is the usual mess.

Two labels are worth treating as public API. good first issue and help wanted are surfaced by GitHub itself — in the repository's contribute page and in global search — so applying them accurately brings people in.

$ gh issue list --label "good first issue" --state open$ gh issue list --assignee @me --state open$ gh issue create --title "CSV export drops rows containing commas" --label bug$ gh issue view 482 --comments

Projects is the layer above: a board or table view across repositories, with your own fields — status, priority, size, iteration — that live on the Project rather than the issue. An issue can be in several Projects at once and knows nothing about any of them. Use this when a repository has enough work that the issue list stops being readable, and not before.

Asking people to write good issues does not work. Giving them a form does. Templates live in .github/ISSUE_TEMPLATE/ and are committed like anything else.

name: Bug reportdescription: Something is brokenlabels: ["bug", "needs-triage"]body:  - type: textarea    id: what-happened    attributes:      label: What happened?      description: Include the exact error message if there is one.    validations:      required: true   - type: textarea    id: steps    attributes:      label: Steps to reproduce      value: |        1.        2.        3.    validations:      required: true   - type: input    id: version    attributes:      label: Version      placeholder: 2.4.1    validations:      required: true

A YAML form gives you real fields with real validation, so an issue physically cannot be submitted without a version number. The older Markdown templates still work and are just a pre-filled body somebody can delete.

Write one of a specific set of words followed by an issue number in a pull request description, and merging that pull request closes the issue automatically — and permanently links the two, so anybody landing on the issue in two years can see the commit that fixed it.

Fixes #482 The CSV writer split on commas without quoting fields, so anyvalue containing one produced a malformed row and the downloadaborted. Quotes fields per RFC 4180 and adds a test.

Closing an issue is not the end of it. A closed issue keeps its whole conversation and is fully searchable — which is why searching closed issues before opening a new one so often finds the answer. And anyone can reopen one if the bug comes back, which keeps the history in one place rather than starting a second thread that has lost all the context.