Everything you need to know to go from zero contributions to your first merged PR - without the parts that waste your time.
Getting your first open source contribution merged is one of those things that sounds straightforward until you try it and discover the gap between the tutorial version and the reality. I want to close that gap.
This is the guide I would have wanted when I started - specific, honest about what is hard, and focused on what actually works rather than what sounds good in theory.
Before you write a single line of code, you need to pick the right project. Most first-contribution attempts fail not because of technical problems but because the project was wrong - too large, too inactive, or too unwelcoming of new contributors.
The specific criteria I would apply: the project should have had a commit in the last thirty days. Projects without recent activity have maintainers who are not actively reviewing PRs, and your contribution may sit unreviewed for months. The project should have issues labelled "good first issue" or "beginner friendly" - this label means a maintainer has explicitly identified this as something a new contributor can tackle. And the project should have responded to at least some recent issues or PRs with something other than silence - a project that ignores contributor questions is not a good environment to start in.
Search GitHub for topics relevant to your skills with the "good-first-issues" filter. Read through five or six candidate projects before committing to one. Look at the tone of maintainer responses in recent issues. A maintainer who gives clear, constructive feedback even when declining a PR is someone you want to learn from.
Once you have found a project, set up the development environment before you touch anything else. Follow the setup instructions in the README or CONTRIBUTING.md exactly, verify that the existing tests pass in your environment, and understand the basic structure of the codebase well enough to know where things live before you start making changes.
This setup step feels slow. It is not. The time you spend here prevents the most common first-contribution failure mode: submitting a PR that cannot be reproduced by the maintainer because your environment had a subtle difference from the expected setup.
When you write your contribution, the single most important thing is to make it smaller than you think it should be. I mean this almost without qualification. A PR that changes one thing, clearly, with appropriate tests, is dramatically more likely to get merged than one that changes five things because you noticed other things to improve while you were working.
The reasons are practical. A focused PR is easier for the maintainer to review, easier for them to reason about the impact of, and easier to approve with confidence. A sprawling PR requires the maintainer to think about multiple independent changes simultaneously, to verify that they don't interact in unexpected ways, and to write review comments on several separate concerns. The cognitive overhead makes them much more likely to ask for it to be split up, which means more round-trips and a longer time to merge.
Write the smallest possible change that addresses the issue. Save the other improvements you noticed for separate PRs after the first one is merged.
Write tests for your change. If the project has tests - and any serious project does - your contribution should include tests that verify the behaviour you added or changed. Look at existing tests to understand the testing patterns the project uses, and match them. A PR without tests in a project that has them signals to the maintainer that you either didn't read the contribution guidelines or are asking them to trust your change without verification. Neither is a good start.
Write a clear PR description. Explain what the change does, why it is needed, and how you tested it. Include a reference to the issue it addresses if one exists. The PR description is your communication to the maintainer - it should give them everything they need to review your change without having to ask clarifying questions.
When you receive review feedback, respond promptly and specifically. Thank the reviewer, address each point of feedback directly, and ask clarifying questions when you don't understand what is being asked for. The review process is a conversation, and maintainers appreciate contributors who engage constructively rather than defensively.
Your first merged PR will take longer than subsequent ones. The second will be faster. After five or six contributions to the same project, you will have developed an intuition for what the maintainers value and how the codebase is structured that makes each subsequent contribution more natural. The compounding is real - and it starts from that first merge.VISIT
Top comments (0)