How to attract contributors to an open-source project
By Bright Oparaji9 min read
Contributors are users who found a way in. You attract them by having users, then making the first contribution small, findable and quickly answered. A call for help on its own does almost nothing.
Most maintainers who want contributors start by asking for them. A line in the README saying "PRs welcome", a post saying "looking for contributors", maybe a Discord channel. Then nothing happens, and the conclusion is that nobody wants to help.
The usual cause is simpler. Nobody contributes to a project they do not use, and the people who do use it cannot see where to start. Both are fixable, and neither is fixed by asking louder.
Contributors come from users, so start there
The path into a project almost always runs in one direction: someone uses it, hits a rough edge, and fixes that edge because it is in their way. opensource.guide describes the same path in its guide to building a welcoming community: user to contributor to maintainer, with the maintainer's job being to remove friction at each step.
That has an uncomfortable consequence. If your project has very few users, it will have very few contributors, and no amount of labelling will change that. The fix at that stage is adoption, which is a different problem with its own playbook. It is covered in how to get your first users for an open-source project, and the general version is on the open-source promotion guide.
If you do have users and still no contributors, the problem is the next step along the path. Each section below removes one piece of friction from it.
Make the first contribution findable
A user who wants to help has one question: what can I do that is small enough to finish this weekend? If the only answer is a list of 140 open issues with no labels, most of them will close the tab.
Use the good first issue label. GitHub's documentation on encouraging contributions with labels explains that the label marks issues suitable for newcomers, and that applying it to a public repository makes those issues more likely to be surfaced elsewhere on GitHub. It is one of the few things a maintainer can do that puts the project in front of people actively looking for something to work on.
Write the issue so a stranger can finish it. A good first issue is one where the hard thinking is already done. Say which file to change, what the change should do, how to check it worked, and that you will review it. "Improve error messages" is a project. "The error in config.ts line 40 says invalid input; it should name the key that failed" is a good first issue.
Keep a few open at all times. Two or three well-written ones beat twenty vague ones. When a newcomer takes one, write the next.
Label the rest too. A short, consistent set of labels (bug, docs, help wanted, needs discussion) lets someone filter for the kind of work they are good at. help wanted is useful for issues you want outside help with that are too big for a first contribution. needs discussion tells people not to start coding yet, which saves them from writing a pull request you will have to decline.
Write a CONTRIBUTING.md that answers the boring questions
A CONTRIBUTING.md is where a would-be contributor finds out whether helping you is going to be easy or a fight with the build. GitHub's guide to setting guidelines for repository contributors says the file can live in the repository root, a docs folder or a .github folder, and that GitHub links to it when someone opens an issue or a pull request. So it is read at the exact moment a contribution starts.
It does not need to be long. It needs to answer:
- How do I get a development copy running? The exact commands, tested on a clean machine.
- How do I run the tests, and what has to pass before you will review?
- What kind of contributions do you want? Bug fixes, docs, new features, all of them? Say so.
- What should I do before writing a large change? Usually: open an issue first.
- How long should I expect to wait for a review?
That last one is rarely written down and it matters more than most. Telling people "reviews usually happen within a week" turns silence from rejection into a known wait.
Your README should point to the file too. In Orviqa's README benchmark, contributing guidance appeared in about 12% of READMEs in the smallest star band and 65% in the largest. That is a correlation in a snapshot, and the detector counts a bare list of contributors as guidance, so read it as what readers of established projects have come to expect rather than as a cause of growth. The README guide has a short contributing section you can copy.
If you maintain several repositories, GitHub lets you set default community health files in a public .github repository on your account or organisation. Any repository without its own CONTRIBUTING.md, code of conduct, issue templates or support file then picks up the default.
Answer the first pull request fast
This is the step that decides whether a first-time contributor becomes a second-time contributor, and it is the one maintainers most often get wrong, usually because they are busy rather than unwelcoming.
Someone who opens their first pull request on your project has done the expensive part. They read your code, set up your environment, and made a change. What they do next depends almost entirely on what you do next. opensource.guide puts it bluntly: leave an issue for a month and the person has probably forgotten about your project. The same guide cites a Mozilla study in which contributors who got a code review within 48 hours were much more likely to come back and contribute again.
The CHAOSS project, which defines community health metrics for open source, has a metric for exactly this: time to first response, the time between an issue or pull request being opened and someone replying to it. Its reasoning is the same. A first reply signals that the project is alive and that someone is paying attention.
A first response does not have to be a full review. Some ways to make it fast without making it expensive:
- Acknowledge on the same day. "Thanks, I will look at this properly on Saturday" costs ten seconds and keeps the contributor engaged.
- Review the smallest pull requests first. First contributions are usually small. Clearing them quickly does more for your contributor count than reviewing a large refactor a day sooner.
- Fix the nitpicks yourself. If a first pull request is right but the formatting is off, push a commit onto it or merge and tidy up. Three rounds of review over whitespace teaches a newcomer that contributing is tedious.
- Say no kindly and with a reason. Some contributions do not fit. Thank the person, explain why, and if there is a related issue that would fit, point to it.
- Thank them in public. A line in the release notes naming the contributor is free and is often the thing people remember.
Would-be contributors check this before they start. The how to contribute guide on opensource.guide tells newcomers to look at whether maintainers respond quickly to pull requests, whether pull requests get reviewed, and how recently any were merged. A row of open, unanswered pull requests from strangers is a sign on the door saying "do not bother".
Widen what counts as a contribution
Code is not the only way in, and for many people it is not the first. Documentation fixes, reproducing bug reports, answering questions in issues, writing examples and improving error messages are all real contributions. They are also much lower risk for a newcomer, which is why opensource.guide recommends starting people on tasks like documentation before code.
Say this in your CONTRIBUTING.md and act on it. Label docs issues. Merge typo fixes promptly and without ceremony. A person who fixed a typo last month and had it merged within a day is a likely candidate for the next small bug.
Hand over ownership on purpose
The last step on the path, from regular contributor to maintainer, rarely happens by accident. Somebody has to offer it.
Watch for people who come back. Someone who has had three or four pull requests merged, or who answers other users' questions without being asked, is telling you they care about the project. Offer them something concrete: review rights on the docs, triage permission on issues, ownership of one module. opensource.guide suggests sharing ownership early and listing contributors in a CONTRIBUTORS or AUTHORS file, and adding a second admin also protects the project if you step away.
It also changes what the project is. A project with one maintainer and many users is fragile, and evaluators notice. If you are tracking this, the number worth watching is first-time contributors per month rather than the total contributor count. The difference is covered in GitHub stars vs active users.
A short checklist
- The project has users. If it does not, work on that first.
- Two or three open issues labelled
good first issue, each with the file, the expected change and how to test it. - A small, consistent label set including
help wantedand something that means "discuss first". - A CONTRIBUTING.md with setup commands, test commands, what you welcome, and how long reviews take.
- A link to it from the README.
- First pull requests acknowledged within a day and reviewed soon after.
- Non-code contributions labelled, welcomed and merged quickly.
- Returning contributors offered a specific responsibility.
None of this needs a community manager or a launch. It is mostly a few files and the habit of replying quickly. The habit is the hard part and the part that counts most.