Opening your first pull request to a project you don't own is oddly nerve-wracking. You've fixed the bug, the tests pass, and yet your finger hovers over the button. What if the maintainer thinks it's stupid? What if you've broken some convention nobody bothered to write down? That anxiety is real, and most of it comes from the fact that nobody ever hands you the rulebook. So here it is, more or less.
None of this is law. Different projects have different cultures, and a good CONTRIBUTING file beats any general advice. But across the projects I've contributed to and helped maintain, the same unwritten norms keep showing up. Learn them once and the whole process gets a lot less frightening.
Start by reading the room
Before you write a line, look around. Read the README and the contributing guide if there is one. Skim recent merged PRs to see what good ones look like — how big they are, how the descriptions read, how the maintainer talks to people. Check the issue tracker to see whether your idea has already been discussed or rejected. Five minutes of this saves everyone an awkward conversation later.
For anything non-trivial, open an issue first or comment on an existing one. "I'd like to fix this — planning to take approach X, does that sound right?" A maintainer would much rather steer you before you've written code than reject a finished PR that went the wrong direction. It also signals that you respect their time, which buys you enormous goodwill.
Keep it small and focused
The single most common mistake on a first contribution is doing too much. You go in to fix a typo and emerge having reformatted four files, renamed a variable, and "tidied up while you were there." Each of those might be fine alone, but bundled together they make the change impossible to review. The reviewer can't tell the meaningful edit from the noise.
One PR, one concern. If you spot other things worth fixing — and you will — note them, open separate issues, and resist the urge to scope-creep. A small, focused change that does exactly what it says is the easiest thing in the world to approve. A sprawling one sits in the queue for weeks while everyone works up the energy to read it.
Write the description the reviewer needs
Your PR description is a gift to a stranger who has no context. Say what problem it solves, link the issue, and explain anything non-obvious about how you solved it. If there's a tradeoff you made or a thing you're unsure about, call it out — reviewers trust contributors who flag their own uncertainty far more than ones who pretend everything's perfect.
Then, when review comments come back, take them gracefully. Critique of your code is not critique of you, even when it stings a little. Respond to every comment, push fixes, and if you disagree, say so politely with your reasoning rather than quietly ignoring it. Maintainers remember contributors who are easy to work with, and that reputation is worth more than any single merge.
Finally, say thank you and be patient. Most maintainers are volunteers fitting this around real jobs and real lives. A PR sitting unreviewed for a week isn't a snub; it's a Tuesday. Show up kind, keep your changes small, and explain yourself clearly, and you'll find the door to open source is far more welcoming than that first hovering finger ever suspected.
