Contributor Guide

How to ship your first pull request

The shortest reliable path from finding a beginner-friendly issue to getting a maintainer-ready pull request merged.

Start here

Choose your starting level

Pick the one that matches your current state, then follow the same phases below.

Complete beginner

Start with the tools, vocabulary, and a documentation-only change. Your goal is to finish one safe loop.

First PR ever

Pick a tiny, recent issue and keep the diff focused. Ask for confirmation before you start coding.

Returning contributor

Use the playbook as a checklist, then spend most of your energy on reproducing and testing the fix.

Phase 0

Install the basic tools

You only need enough local tooling to clone the repository, make a branch, run the project checks, and push your work.

git

Git tracks your work and lets maintainers review exactly what changed.

git --version

gh

GitHub CLI helps you fork, clone, authenticate, and open pull requests without leaving the terminal.

gh auth login
gh repo fork OWNER/REPO --clone --remote

Editor

Use an editor that can search the whole repository, run formatters, and show changed files clearly.

code .

Phase 1

Pick the right issue

A good first issue is not just small. It is current, understandable, and reviewable by someone who already maintains the project.

  1. Claim it

    Leave a short comment that names the exact issue and asks whether the scope still makes sense.

  2. Read the rules

    Read CONTRIBUTING, the README, open pull requests, test commands, and code style notes before changing code.

  3. Fork + branch

    Create your own copy and work on a branch named after the task, not on main.

  4. Set up + reproduce

    Install dependencies, reproduce the problem, and write down the command or screen where you saw it.

  5. Ship a tiny diff

    Change the least code needed. Avoid drive-by refactors, dependency upgrades, and unrelated formatting.

  6. Open the PR

    Explain what changed, how you tested it, and any limits. Make the reviewer's first pass easy.

Pause points

Red flags before you invest more time

Stopping early is better than forcing a pull request that cannot be reviewed.

  • You cannot run the project locally after following the documented setup.
  • The fix requires guessing product behavior without maintainer input.
  • The issue asks for a large feature, redesign, migration, or architecture decision.
  • A maintainer has asked first-time contributors not to work on the area.

Reference

Glossary

Fork
Your personal copy of a repository. You push your branch there before opening a pull request.
Branch
A movable line of work. Use one branch per issue so your changes stay reviewable.
Pull request
A request for maintainers to review and merge your branch into the project repository.
Diff
The smallest meaningful set of changes that solves the issue without unrelated cleanup.
CONTRIBUTING
A project-specific checklist for setup, style, tests, and pull request expectations.

FAQ

Common first PR questions

What if the maintainer hasn't replied in a week?

Post one concise follow-up with your current status and a direct question. If there is still no reply, choose another issue instead of waiting indefinitely.

What should I do when setup fails?

Say what you tried, paste the exact error, include your operating system and tool versions, and ask for the next debugging step.

Can my first PR be documentation only?

Yes, if the repository welcomes documentation changes. Clear docs, examples, typos, and broken links are legitimate contributions.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.