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 Velloreth
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 issueorhelp wantedlabel
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:
| Label | Meaning |
|---|---|
good first issue | scoped for a newcomer |
help wanted | the maintainer wants help |
bug | a defect |
documentation | a docs change |
beginner | a 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.
Related reading
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.