I'm fairly new to contributing to other people's projects. Lately a handful of my small fixes have been merged into Python projects I'd never touched before, and a lot more are still waiting on review. Here's what I've learned so far.
1. Prove the bug before you touch the fix
The fixes that went smoothly all started the same way: a small test that fails on the current code and passes with my change. Not a description of the bug, not a screenshot, a test.
It does two jobs. It shows the maintainer the problem in a way they can run in ten seconds, and it stops the bug from quietly coming back later. If I couldn't write that test, I usually didn't understand the bug yet.
2. "Fixed" in a commit message is a claim, not a fact
A lot of the bugs I found were in code where an earlier commit said it had already fixed that exact thing. The fix was partly there: it handled the case in the commit message, but not a slightly odd input next to it.
Now when I read "fixed X" in a history, I treat it as something to check, not something to trust. That includes my own commits, and the ones my AI tools write for me.
3. Small and focused wins
On one project I sent seven separate small PRs instead of one big one. The maintainer merged all seven and said small, focused PRs were nice to review. That stuck with me. A reviewer is a volunteer doing me a favour, and a ten-line change with one test is something they can say yes to on a lunch break.
4. Run the project's checks exactly the way CI does
Running the linter and tests "my way" isn't the same as running them the project's way. Now I open the CI workflow file first and run the same commands, with the same versions, before I push. And when CI does go red, I check whether it's red on the main branch too before assuming it's my fault. Cheap habit, saves an awkward "sorry, one more commit".
5. Read the contributing rules, even on tiny repos
Some projects want you to comment "I'd like to take this" on an issue before you start. Some want a sign-off line on every commit. Some say outright that they'd rather get an issue than a PR. Following the house rules costs two minutes and tells the maintainer you respect their time.
6. Say only what you checked
In PR descriptions I try to write exactly what I ran and what I didn't. "These 5 tests also fail on main for network reasons" is better than letting the reviewer find that out. Being plain about the limits seems to build more trust than sounding confident.
7. The best outcome isn't always the merge
On one project the owner merged my test-only PR and then opened a follow-up issue to close the rest of the gaps it pointed at. That felt better than the merge itself. A good bug report can be more useful than the fix.
I'm still new at this, and most of my PRs are still waiting on review. If you maintain a project and have advice for first-time contributors, I'd genuinely like to hear it.
Top comments (0)