Choosing Your First Issue

ℹ️

The Right Issue Makes All The Difference

Your first issue sets the tone for your entire contribution journey. Choose wisely.

Issue Selection Criteria

┌─────────────────────────────────────────────────────────────────────────────┐
│                       IDEAL FIRST ISSUE CHECKLIST                           │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ✓ Labeled "good first issue", "beginner-friendly", or "help wanted"       │
│  ✓ Clear description of what needs to be done                              │
│  ✓ No one else is actively working on it                                   │
│  ✓ Maintainer has responded recently (issue is monitored)                  │
│  ✓ Small scope (can be completed in one PR)                                │
│  ✓ Doesn't require deep understanding of codebase                          │
│  ✓ Has some guidance or pointers to relevant code                          │
│  ✓ Not stale (opened within last 3 months)                                 │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Good First Issue Labels

Different projects use different labels:

Label	What It Means
`good first issue`	GitHub's official label for beginners
`first-timers-only`	Reserved specifically for first-time contributors
`beginner` / `beginner-friendly`	Suitable for beginners
`help wanted`	Maintainers need help (may not be beginner)
`easy` / `low-hanging-fruit`	Relatively simple to implement
`documentation`	Doc improvements (often good for first-timers)
`starter issue`	Another beginner-friendly variant

Finding Issues

GitHub Search Queries

# Good first issues in a specific repo
repo:facebook/react label:"good first issue" is:open
 
# Help wanted, not assigned
repo:vercel/next.js label:"help wanted" no:assignee is:open
 
# Documentation issues
repo:microsoft/vscode label:"documentation" is:open
 
# Issues without PRs linked
repo:org/project label:"good first issue" is:open linked:pr is:unlinked

Project-Specific Locations

Check Issues tab

Go to github.com/org/project/issues and filter by labels.

Check Contributing Guide

Some projects list beginner issues in their CONTRIBUTING.md.

Check project roadmap

Projects sometimes tag issues for upcoming releases that need help.

Check community channels

Discord/Slack often has channels specifically for finding issues.

Issue Evaluation Matrix

┌─────────────────────────────────────────────────────────────────────────────┐
│                         ISSUE EVALUATION                                    │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│              GREEN LIGHT                    RED LIGHT                       │
│              ═══════════                    ═════════                       │
│                                                                             │
│  Clarity     Clear description              Vague "fix the thing"           │
│              Steps to reproduce             No reproduction steps           │
│              Expected vs actual             Unclear expected behavior       │
│                                                                             │
│  Scope       Self-contained change          Requires multiple PRs           │
│              <200 lines estimated           Major refactoring needed        │
│              One feature/fix                Kitchen sink of changes         │
│                                                                             │
│  Activity    Comments in last month         Last comment 6+ months ago      │
│              Maintainer responded           No maintainer engagement        │
│              Discussion happened            Issue opened and abandoned      │
│                                                                             │
│  Assignment  No one assigned                Already assigned                │
│              No linked PRs                  Linked PR exists                │
│              Open for grabs                 "Working on it" comment         │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Issue Types for Beginners

Documentation

Best for: Absolute beginners

Fix typos
Clarify instructions
Add examples
Update outdated info

Risk: Very low

Bug Fixes

Best for: Those with some coding experience

Clear reproduction steps
Well-defined expected behavior
Self-contained fix

Risk: Low-medium

Test Coverage

Best for: Learning the codebase

Add tests for untested code
Fix flaky tests
Improve test utilities

Risk: Medium

Small Features

Best for: Confident beginners

Add a flag/option
Improve error messages
Add a small UI element

Risk: Medium

⚠️

Avoid These for First Contribution

Major new features
Breaking changes
Performance optimizations
Anything labeled "complex" or "advanced"
Issues with ongoing debates in comments

Before Claiming an Issue

Read the entire thread

Read ALL comments. Someone might have already solved it, or there might be important context.

Check for linked PRs

Look in the sidebar for "Linked pull requests". If there's an open PR, the issue is taken.

Check recent comments

Look for "I'm working on this" or "@maintainer can I take this?"

Understand the scope

Make sure you understand:

What exactly needs to be done
Where the code lives
How to test the fix

Comment to claim

Wait for response

Don't start coding until a maintainer acknowledges you. They might have additional context or want to assign it officially.

Sample First Issues by Type

Documentation Issue

Title: Clarify installation instructions for Windows users
 
Labels: good first issue, documentation
 
Description:
The current README says "run npm install" but Windows users have 
reported issues with native dependencies. 
 
Task:
- Add Windows-specific instructions
- Include required Visual Studio Build Tools setup
- Test on a Windows machine if possible

Why it's good: Clear scope, no code changes, helps real users.

Bug Fix Issue

Title: Button click handler fires twice on mobile
 
Labels: good first issue, bug
 
Description:
On mobile devices, clicking the submit button fires the 
handler twice. This causes duplicate form submissions.
 
Steps to reproduce:
1. Open app on mobile Safari
2. Fill out form
3. Tap submit button
4. Observe network tab shows two requests
 
Expected: One request
Actual: Two requests
 
Hint: Look at src/components/Button.tsx, the touchend event 
might be the issue.

Why it's good: Clear reproduction, hints provided, self-contained.

Test Issue

Title: Add tests for UserService.updateProfile()
 
Labels: good first issue, testing
 
Description:
The updateProfile method in src/services/user.ts has no 
test coverage. Add tests for:
- Successful profile update
- Validation errors
- User not found case
 
Related file: src/services/user.test.ts (add tests here)

Why it's good: Clearly scoped, teaches the codebase, valuable contribution.

Issue Claim Template

Use this template when commenting on an issue:

Hi @maintainer! 👋
 
I'd like to work on this issue. Here's my understanding of what needs to be done:
 
**Task:** [One sentence summary]
 
**Approach:** 
- [Step 1]
- [Step 2]
- [Step 3]
 
**Questions:**
- [Any clarifying questions]
 
I'm a [new/intermediate] contributor. Is it okay if I take this one?

Your First Issue Checklist

Issue has a beginner-friendly label
Issue was active in the last 3 months
No one is currently assigned or working on it
I fully understand what needs to be done
I know where the relevant code lives
Scope is small enough for one PR
I've commented to claim and got acknowledgment
I'm ready to work on it within the next few days

Understanding Codebases Overview