How to make your first meaningful open source contribution (that isn’t just a docs fix)

A practical guide to creating contributions that are real to someone.

The standard guidance for participating in open source development is to find a project, identify a “good first issue,” correct a typo or document something, and submit a pull request. That is good guidance, but it stops too short. It will create a merged pull request. But it will not show you how to become a participant.

Here’s the truth. In 2024, GitHub reported 1.4 million new open source participants for the very first time. Research by academics indicated that 58% of those participants created one or two commits and then stopped.

There is a divide between sending a pull request and being an actual member of a project, and most guides ignore the divide.

This guide is about making a contribution that actually matters to someone and learning how to belong to a project, not just submit to one.

Start with a project you actually use

Most new contributors select a project to participate in from the “popular” list on GitHub and then search for something to do. Brian Douglas, founder of OpenSauced and formerly of GitHub, puts it bluntly: the best “good first issue” is an issue you create yourself after you have used the product and realized a genuine problem. The Apache Foundation states the same thing: the key to participating in any open source project is having a personal motivation for doing so.

Find a project you currently use. Look for something that has caused you frustration, something that you feel is incorrect in its behavior, something that has generated a confusing error message, something that has an unrefined workflow. That frustration is your gateway to begin. It indicates you already understand the problem, which gives you an advantage over many first-time contributors when you create your first lines of code.

After you identify a project, take some time to observe before you contribute. Look at the current issues. See how maintainers react to pull requests. Determine if the project includes a CONTRIBUTING.md file. See if recent PRs receive reviews in a timely manner. See if other community members outside of the core team are actively participating. Smaller projects that are easily accessible to the maintainer are generally easier to contribute to than large projects with a long delay for reviews.

How to read a codebase without getting lost

You do not need to learn everything about a project to contribute to it. You need to learn the “surface area” surrounding the problem you intend to resolve.

Kent C. Dodds recommends starting with the contributing guidelines first, found in the README or a CONTRIBUTING.md file. If the project doesn’t have one, file an issue and ask. From there, follow the code path related to your issue. Use git blame and git log to determine why things are the way they are. If you would like to quickly find the most important files in a project, this command will display the ten most frequently modified files:

git log --pretty=format: --name-only | sort | uniq -c | sort -rg | head -10

In essence, you should work inward toward the specific problem you wish to resolve, as opposed to attempting to understand the overall architecture of the project prior to starting. Repair a bug and you will naturally learn the system. Attempt to understand the system and you will likely become stalled before you get started.

Read more: Why open source is critical for the continued advancement of new tech

Why “Good first issues” aren’t always the best entry point

While good first issues are suitable for initial participation, some of the most impactful first contributions are derived from labels that are unrelated to “good first issues.”

Daniel Block, who has maintained several open source projects including OpenSearch since 2008, shared a tactic that perfectly exemplifies this concept. When a user reports a bug, Daniel typically responds with: “Thank you for reporting this issue! Would you like to help? Perhaps write a failing test that replicates this issue?” 

He has discovered that contributors who develop the failing test typically determine the solution to the bug as well. A failing test that demonstrates a bug exists is among the most valuable items you can provide to a maintainer, since demonstrating a bug exists is among the most difficult and time-consuming tasks for a maintainer.

Other high-impact contributions that do not require extensive knowledge of a project include enhancing a confusing error message you experienced while using the product, providing assistance to other users via GitHub issues (Sebastián Ramírez, creator of FastAPI, has stated this provides value greater than most code contributions) and developing a missing integration test for an existing function.

The common theme is to seek work that reduces the maintenance time for the maintainer, as opposed to seeking work that increases the maintainer’s review burden.

Talk to maintainers before you write a single line of code

Post a comment on the issue before you build anything. Explain what you plan to accomplish, and inquire if your plan makes sense.

That is not asking for approval. That is preventing you from building something the maintainer will reject, or duplicating work another contributor is performing. Stan Lo, a developer of Ruby developer tools, described the test he uses to evaluate each contributor: Can they describe the problem they are resolving, and why they selected the exact method they employed to resolve it? If you can respond to both of these inquiries succinctly in the comments section of the issue before you begin coding, you have already demonstrated more forethought than most first-time contributors.

Maintainers are usually volunteers and have limited time. Demonstrate that you have studied the contributing guidelines and that you have studied the conversation prior to asking questions. There is one exception: some projects (e.g., Creative Commons) explicitly state that you should not ask for issue assignments and simply submit the work. Always consult the project’s own CONTRIBUTING.md rather than applying a generic rule.

Read more: The AI slop problem threatening open source maintainers

Avoid the mistakes that get you ignored

The timing is crucial. Sixty percent of open source maintainers have quit or have considered quitting, and forty-four percent cite burnout as the reason. Burnout is directly associated with reviewing poor quality contributions. Artem Sapegin, former maintainer of React Styleguidist, quit open source completely due to the amount of time spent managing contributions, stating that “managing contributions requires more time than I would need to implement the same features myself.” His primary complaint was regarding hit-and-run pull requests where contributors submitted code and did not respond to feedback.

With that in mind: Keep your first PR small and focused. Test the project locally prior to submitting. Reply to feedback from reviewers in a timely fashion, ideally within 24 hours. A PR that goes inactive after receiving feedback once is worse than not submitting a PR at all.

And increasingly, be able to explain every line of code you submit. Mitchell Hashimoto, creator of Ghostty, implemented a system of vouching for contributors, primarily due to individuals who could not explain the code they contributed. If you use AI tools to assist you with writing your contribution, that is acceptable. If you cannot explain every line of code you submit, you are not prepared to submit it.

Your first contribution won’t be your best, and that’s the point

Your first meaningful contribution may not be your best work. And that is okay. The objective is to acquire experience in how an open source project actually functions from within, and develop the confidence to perform it again.

Daniel Stenberg, creator of cURL and one of the longest-running open source maintainers, continues to say: “There is no such thing as a too small patch or issue.” The contribution that truly matters is the contribution where you comprehended the problem, worked with the project honestly, and delivered something real. Begin there. The rest will follow.

More from We Love Open Source

• OpenClaw: Anatomy of a viral open source AI agent
• Getting started with OpenClaw: Complex tasks from a simple chat
• Why open source is critical for the continued advancement of new tech
• The AI slop problem threatening open source maintainers
• Stop opening firewall ports and start using identity