The anatomy of a good first issue

A good first issue label is a promise: this is small, self-contained, and someone new can finish it without a maintainer holding their hand. Most projects break that promise. The label is there, but the issue behind it is a two-word title and a shrug.

Here’s the template every oss.codes repo uses.

1. State the outcome, not the task

Bad: “Refactor the config loader.” Good: “make dev should fail with a clear message when .env is missing, instead of a stack trace.”

A new contributor can verify the second one. They know they’re done when the message appears.

2. Point at the code

Every good first issue links the exact file and line where the work starts:

The check belongs in src/config.ts around line 40, next to the existing
`requireEnv()` calls. Add a test in tests/config.test.ts.

Nobody’s first PR should begin with a 40-minute scavenger hunt.

3. Show the finish line

Spell out what “merged” looks like:

• Missing .env prints error: copy .env.example to .env
• Exit code is non-zero
• A test covers the missing-file case

When the checklist is done, the PR is done. No guessing whether a reviewer will want more.

4. Leave the fun part

Don’t over-specify. The best first issues describe the what and the where, then trust the contributor with the how. That’s where people fall in love with a codebase — the small, satisfying “oh, I see how this fits together.”

Why we bother

Contributors don’t leave because the work is hard. They leave because the on-ramp is invisible. A well-written first issue is the cheapest, highest-leverage thing a maintainer can do — it turns a curious stranger into a repeat contributor, and repeat contributors turn into maintainers.

Want to try one? Our good first issues are always open.