Skip to content

We use analytics cookies to see how the site is used. They are only set if you accept. Accepting also turns on session recording (pages viewed, clicks and scrolls) so we can fix problems; what you type stays hidden. It also lets Meta (Facebook) see your visit, so we can measure our ads. Read the privacy policy

A newspaper classified ad headed good first issue, with a label chip and a box listing file, expected result, test and size.

The Contributor Courier

Help wanted - one evening - tests included

Good First Issues: Rewriting One Vague Ticket So a Stranger Can Finish It

A newcomer opens your Issues tab and sees "improve error handling". Here is the same ticket rewritten, the six things it needed, and where GitHub shows the label.

The first open ticket reads "Improve error handling". Nothing says where, what done looks like, or whether it takes an hour or a month, so the stranger closes the tab. A good first issue answers those three questions before anyone has to ask.

This post takes one invented ticket from a made-up project and rewrites it, then covers where GitHub shows the good first issue label and how to stop writing vague tickets by accident. Facts about GitHub come from its docs, read on 10 November 2026.

The ticket nobody takes

Title: Improve error handling
Labels: good first issue

The config parser has bad error handling.
Someone should look at it.

The label is on, so the ticket claims to be easy. It is not: the reader must find the parser, decide what "bad" means and invent the fix and its test. Labeling a ticket does not make it approachable. Writing it does.

The same ticket, rewritten

Title: parseConfig() throws a bare TypeError when the file is missing
Labels: good first issue, help wanted

What happens
  parseConfig("missing.json") throws:
  TypeError: Cannot read properties of undefined (reading 'trim')

What we want
  A ConfigError with the message: Config file not found: missing.json

Where to look
  src/config/parse.ts, the readFile() call on line 14
  tests/parse.test.ts has two similar cases to copy

How to check your work
  npm test          (the new test must fail before your change)

Size: about one evening. No design decisions needed.
Ask here if you are stuck. A maintainer replies within two days.

What each line is for

LineThe question it answers
Title with the real errorWhat is wrong? A stranger can search the exact message.
What happens / what we wantWhat does done look like? One input, one expected output.
Where to lookWhere do I start? A file, a line and a test to copy.
How to check your workHow do I know I am finished? One command.
Size and "no design decisions"Is this safe to start? The reader knows the scope before cloning.
Who answers, and whenWill anyone notice my pull request?

The six-point check before you add the label

  • The title names a symptom or a result, not a topic like "improve" or "refactor".
  • One input and one expected output are written down.
  • At least one file path is named.
  • A command proves the fix. Ideally a test that fails first.
  • No open question needs the maintainer's decision. If one does, settle it in the ticket first.
  • You can finish it yourself in under an hour. That is a fair test of whether a stranger can finish it in an evening.

Where GitHub shows the label

GitHub says you can apply the good first issue label to issues in a public repository so people can find them when searching by label. It also says it uses an algorithm to pick the most approachable issues in each repository and surface them in various places, and that adding the label can increase the likelihood that yours are surfaced.

The label is one of GitHub's default labels, described as "Indicates a good issue for first-time contributors", next to help wanted. Issues carrying it populate the repository's contribute page. Repositories created a while ago, or whose owners edited the defaults, may not have it: check the Labels page and create it if it is missing.

The label gets a stranger to the ticket. The ticket text keeps them there.

Point newcomers somewhere: CONTRIBUTING.md

GitHub shows a link to your contributing guidelines when someone opens an issue or a pull request, on the repository's contribute page, in a Contributing tab next to the README and code of conduct, and in the sidebar. The file can live in the root, docs or .github. If a repository has more than one, GitHub picks the .github one first, then the root, then docs.

Keep it short enough to read on a phone: how to run the tests, how to name a branch, and a link to your good first issues.

Stop vague tickets at the source with an issue form

Issue forms are YAML files in .github/ISSUE_TEMPLATE. GitHub marks them as public preview, so check the current syntax before copying. This sketch asks the reporter for the fields a newcomer needs, and tags the ticket for you to review:

# .github/ISSUE_TEMPLATE/small-task.yml
name: Small task
description: A scoped task a newcomer could pick up.
labels: ["help wanted"]
body:
  - type: textarea
    id: now
    attributes:
      label: What happens now
    validations:
      required: true
  - type: textarea
    id: want
    attributes:
      label: What should happen
    validations:
      required: true
  - type: input
    id: where
    attributes:
      label: Where to look (file path)
  - type: input
    id: check
    attributes:
      label: Command that proves it is fixed

It leaves out good first issue on purpose. Add that label by hand, after you run the six-point check.

Then answer fast

Open Source Guides says a Mozilla study found that contributors who received code reviews within 48 hours came back and contributed again at a much higher rate. We did not open the study itself, so treat that as the guide's claim. The advice that follows from it needs no number: a reply that says "thanks, I will look this week" costs a minute and keeps the contributor.

Questions

How many good first issues should I keep open?

Enough that a newcomer has a choice, and no more than you can answer quickly. Three well written tickets beat thirty vague ones. GitHub gives no official target.

Should I assign the issue to the first person who asks?

That is your call. A short comment such as "go ahead, this is yours for two weeks" prevents duplicate work and tells you when to free the ticket again.

My project has no easy tasks.

Documentation fixes, a missing test for an existing function and a clearer error message are the usual starting points. The rewritten ticket above is the third kind.

Sources