What a good first issue actually looks like

We had 62 issues labelled good first issue, of which eleven had been sitting open for more than a year, and four had a first-time contributor start work and then go quiet, which is the outcome that ought to bother a project more than any of the others, because that person tried once and is not going to try again.

Reading them together, the pattern was obvious and a little embarrassing: most of them had never been first issues, they were things a maintainer did not want to do and had labelled optimistically on the way past. "Improve error messages" is not a task, whatever the label says; it is a research project with a friendly name.

The four things a first issue needs

• A file. Naming the file, ideally the function, removes the single largest cost for a newcomer. That cost is not writing the code, it is finding where the code lives in a repository they have never seen.
• A done condition. Something checkable. "This test passes", "this command prints X", "this parse warning appears for the attached document". If the maintainer cannot state it, the issue is not ready for anybody, first-timer or not.
• A named reviewer who has already agreed. Not a rota, not a team. A person who said yes before the issue was labelled. Waiting two weeks for a review on your first contribution is how a contributor stops being one.
• An honest size. We write the number of lines we think it is. Being wrong about that is fine and useful; being silent about it means the contributor discovers the scope halfway through an evening they had set aside.

An issue that only makes sense to somebody who already knows the codebase is a note to yourself with a label on it.

What the rewrite did

Of the 62, we rewrote and kept 24, closed or relabelled 31 as ordinary work, and found that 7 had already been fixed by somebody who never went back to close the issue. The label went from a graveyard to a list of two dozen real tasks. Much smaller, and it has the advantage of meaning something.

The review-time row is doing most of the work in that table, and it is worth sitting with that for a moment, because everything else we changed was about the wording of the issue itself, while the single change that moved contribution volume most was a named person agreeing in advance to look at the result quickly.

The kinds of task that work

Concrete, bounded, and touching a part of the system where being wrong is visible immediately:

• A date format for a locale we do not parse yet: a table entry, a test case, and a document in the fixtures.
• A parser failing on one attached document, with the expected output stated.
• A flag that exists in one command and not its sibling.
• A documentation page that is wrong in a specific way, with the correct behaviour described.

The kinds that never work, no matter how well-meant: anything touching the retrieval ranking, anything requiring a judgement call about output format, anything whose test would take longer to write than the fix, and anything phrased as "investigate".

The part that is not about issues

A first contribution is mostly a social event and only partly a technical one, since the commit itself is usually small, and what actually decides whether the person comes back is whether anything happened afterwards: a review inside a day, a merge, a line in the release notes with their name on it, and somebody telling them which bug it fixed for real users.

None of that scales if a project treats it as a chore, though it is entirely sustainable at twenty-four issues, which is the other and less obvious argument for having fewer of them.

The labelled issues live in github.com/getquire/quire. If one of them is missing a file, a done condition or a reviewer, that is a bug in the issue and worth saying so.

---