Skip to content
Velloreth
Programming 6 min read

Contributing to Open Source: A Practical Start

Find a project, find an issue, and get a pull request merged. Learn the etiquette, the workflow, and the mistakes that stall a contribution.

By

Why contribute

You learn from a real codebase. A production project has constraints a tutorial does not.

You get feedback from experienced reviewers. A review of your change is a design conversation.

You build a public record. A merged pull request is evidence of your work.

You fix a problem you have. The most motivated contribution is a bug that affects you.

Finding a project

Start with a library you use. You know the problem it solves, and you can judge whether a change is useful.

The signals of a healthy project:

  • A recent commit
  • A responsive maintainer
  • A contributing guide
  • A test suite
  • A CI pipeline
  • A good first issue or help wanted label

The signals to avoid:

  • No commit in a year
  • Many open pull requests with no review
  • No tests
  • A hostile issue thread

A small project is often better for a first contribution, because the maintainer has time to review.

Finding an issue

The labels:

LabelMeaning
good first issuescoped for a newcomer
help wantedthe maintainer wants help
buga defect
documentationa docs change
beginnera small change

A documentation fix is the lowest-risk start. A typo, a missing example, an unclear sentence.

A test for an uncovered case is a strong first contribution, because it is useful and it cannot break anything.

A small bug with a clear reproduction is a good target.

A large feature is a poor first contribution, because the design discussion is long and the review is heavy.

Before you start

Read the contributing guide. It states the workflow, the style and the test requirement.

Read the code of conduct. It states the expected behaviour.

Read the issue template. It states what a report needs.

Search the issues and the pull requests. The problem may already be reported or fixed.

Comment on the issue. Say that you would like to work on it, and ask any question about the approach.

Why: it claims the work, so two people do not duplicate it, and it gives the maintainer a chance to say whether the change is wanted.

The workflow

# Fork the repository, then clone your fork
git clone https://github.com/you/project.git
cd project

# Add the upstream
git remote add upstream https://github.com/original/project.git

# Create a branch
git checkout -b fix/typo-in-readme

# Make the change, then test it
npm test

# Commit
git commit -m "docs: fix typo in the installation section"

# Push to your fork
git push origin fix/typo-in-readme

Then open a pull request against the upstream’s main branch.

Keep the branch up to date with the upstream, and rebase rather than merge if the project prefers it.

The pull request

A good description:

## What

Fixes the typo in the installation section.

## Why

The command as written fails on macOS.

## How to test

Run the command in the README on macOS 14.

The sections: what, why, and how to test.

Link the issue. Fixes #123 closes it on merge.

One logical change. A pull request that fixes a bug and reformats a file is two changes, and the reformatting makes the fix hard to review.

Follow the commit convention. A project that uses conventional commits expects a fix: or docs: prefix.

Run the tests and the linter before you push.

The review

A review is a conversation, not a verdict.

Respond to every comment, even with a short acknowledgement.

Push a new commit rather than force-pushing during a review, unless the project asks for a rebase. A force-push makes the review hard to follow.

Ask a question if a comment is unclear. A maintainer would rather explain than have you guess.

Be patient. A maintainer is often a volunteer, and a review can take a week.

A rejection is normal. The reason is the useful part. Ask what would make it acceptable.

The etiquette

Do not @ a maintainer for a review. It is a demand on their attention.

Do not open a pull request for a large change without an issue. The design may be rejected.

Do not reformat unrelated code. It makes the diff unreadable.

Do not argue about a style preference. Follow the project’s convention.

Do not take a rejection personally. It is about the change.

Say thank you. A maintainer spent their time on your contribution.

A first contribution plan

A first contribution is easier with a plan of a few weeks rather than a single attempt. The first week is reading: pick a library you use, read its contributing guide, and read a few merged pull requests to see the standard. The second week is a documentation change, which teaches the fork, the branch, the commit and the pull request with almost no risk. The third week is a test for an uncovered case, which teaches the test setup and gives the maintainer something useful. The fourth week is a small bug, which is the first change to the product code. By that point the workflow is familiar, and a larger contribution is a normal next step rather than a leap. The plan also produces a public record of four merged contributions, which is worth more than one large pull request that stalled.

Common mistakes

A large first contribution. It is usually rejected or stalled.

No comment on the issue. Two people do the same work.

A pull request with no description. The reviewer has to guess the intent.

A diff that includes a reformat. The change is hidden.

Not running the tests. The CI fails and the review stalls.

A force-push during a review. The comments lose their context.

A CLA that was not read. It can be a reason not to contribute.

Taking a rejection personally. It is about the change.

Abandoning a pull request. A stale pull request is closed, and the work is lost.

A quotable summary

Start with a library you use, and pick a documentation fix, a test, or a small bug rather than a large feature. Read the contributing guide, comment on the issue to claim it, and keep the pull request to one logical change with a description of what, why and how to test. A review is a conversation, a rejection is normal, and the reason is the useful part.

For the git side, see git-rebase-vs-merge and git-commit-messages-guide. For the broader context, code-reading-strategies and building-a-portfolio-project.

Frequently asked questions

How do I find a project to contribute to?
Start with a library you already use, because you know the problem it solves. Look for a good-first-issue or help-wanted label, a recent commit, and a responsive maintainer. A project you use is a project where you can judge whether a change is useful.
What should my first contribution be?
A documentation fix, a test for an uncovered case, or a small bug. These are low-risk, they teach you the workflow, and a maintainer can review them quickly. A large feature as a first contribution is usually rejected or stalled.
Should I comment on the issue before starting?
Yes. It tells the maintainer and the other contributors that the work is in progress, so two people do not duplicate it. It also gives the maintainer a chance to say whether the change is wanted before you write it.
How big should a pull request be?
One logical change. A pull request that fixes a bug and reformats a file is two changes, and the reformatting makes the fix hard to review. A small, focused pull request is reviewed and merged faster.
What if my pull request is rejected?
It is normal, and the reason is the useful part. A maintainer may disagree with the approach, the scope, or the timing. Ask what would make it acceptable, and treat the answer as a design review rather than a rejection of you.
Do I need to sign a CLA?
Some projects require a Contributor License Agreement, which grants the project the rights to your contribution. Read it before you start, because a CLA can be a reason not to contribute to a particular project. Many projects do not require one.