Issues and Keeping Track of Work

An issue is a written note that something should change: a bug, an idea, a question. It costs a minute, it survives the conversation that produced it, and on GitHub it is where most real work starts.

It is the same argument as commit messages, one level up. A decision that lives only in someone's memory is a decision nobody can find later.

What goes in one

For a bug, four things: a title someone can scan, what you expected, what actually happened, and how to see it yourself. That last one is the difference between a report and a wish.

Title: Sightings list unreadable on a phone

Expected: the list of recent sightings fits the screen width.
Actual: the dates run off the right edge and get cut off.
To see it: open the home page on a phone, or make the browser
window narrower than about 400px. Screenshot attached.

For an idea or a question, less structure is needed. State the thing, say why it would matter, and stop.

Organizing them

Labels sort issues by kind: bug, idea, documentation. The label good first issue is a convention across open source, marking work suitable for a newcomer — and it is where Chapter 9 suggests you start.

Assignees say who is doing it, which mostly prevents two people doing the same thing.

That is enough structure for a small project. GitHub offers milestones, project boards and more; they are useful at scale and pure overhead for two people and a club website.

Connecting an issue to the work

Mention an issue's number anywhere on GitHub and it becomes a link:

git commit -m "Wrap the sightings list on narrow screens (#12)"

Better still, write Closes #12 in the pull request description. When that pull request merges into the default branch, GitHub closes the issue automatically — the work and the reason it existed are linked permanently, without anybody remembering to tidy up.

Issues as conversation

Questions and decisions live in the issue, which means the reason behind a change is findable a year later by someone who was not there when it was made.

Between the issue, the pull request, and the commit messages, a well-run project answers "why is this like this" three times over. A minute of record-keeping buys an answer a year later, which is the only reason any of it is worth doing.

On your own project

Opening issues on a project only you touch feels odd for about a week, and then becomes obviously useful.

A solo project is exactly where written notes are worth most, because nobody else remembers what you meant and future-you is a stranger with no context. It also means the ideas you have on a Tuesday and cannot act on until Saturday are somewhere other than a text file called todo.