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

Use these cards as a static selector. 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.

Good signals

  • The issue is recent or has a maintainer reply.
  • The repository has setup instructions that still work.
  • The expected change can fit in one small pull request.
  • Tests or manual verification steps are described.

Red flags

  • Multiple people are already working on the same issue.
  • The issue is vague, old, or blocked by design discussion.
  • The change touches security, billing, database migrations, or release automation.
  • The project has no recent maintainer activity.

Decision tree

  1. Can you explain the request in one sentence?
  2. Can you reproduce or verify the problem locally?
  3. Can the change stay small and isolated?
  4. If all three are yes, ask to take the issue.

Phase 2

The 6-step playbook

Keep the loop boring and predictable. Small pull requests are easier to review, easier to fix, and easier to merge.

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.

gh repo fork OWNER/REPO --clone --remote
cd REPO
git checkout -b docs/fix-install-note
pnpm install
pnpm test
git status
gh pr create --fill

Templates

Copy-paste templates

Adapt the wording, keep it specific, and avoid promising more than you can finish.

Claim comment

Hi! I'd like to work on this issue.

I plan to keep the change scoped to:
- ...

Does that approach sound right before I start?

PR description

## What changed
- ...

## How I tested
- ...

## Notes
- This is my first contribution to this repository, so feedback is welcome.

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.

After first merge

Turn one contribution into a repeatable habit

Thank the reviewer, note the commands that worked, save the project conventions, and look for the next issue that is only slightly harder than the last one.