Don't Open a Pull Request Yet

You want to contribute to open source, but you do not want to be that person.

Not the one who opens a pointless pull request just to add their name to a README.md. Not the one who pastes in AI-generated code, wraps it in a polished PR description, and assumes “looks right” means “is right”. And not the one who leaves a maintainer with more work than before they saw your name in the notifications.

That fear is healthy.

Because the uncomfortable truth is this: a lot of visible contribution is not useful contribution. A maintainer is rarely asking, “Did this person submit something?” They are asking three quieter questions:

Is this needed?
Is this correct?
Is this easy to trust?

Most weak contributions fail on one of those three points before the code itself matters.

That is why good open-source contribution starts earlier than most people think. It does not start with a pull request. It starts with context.

Context comes first

People love to say, “Just find an issue and start.”

That is fine advice if your goal is activity. It is bad advice if your goal is usefulness.

A repository is not a bucket of chores waiting for strangers. It is a living system with trade-offs, history, backlog pressure, and people trying to keep it moving. If you open a pull request before you understand any of that, you are not really helping yet. You are asking someone else to assess your judgment.

That is why tiny, visible changes can still be poor contributions. A one-line diff is not automatically a one-minute ask. Someone still has to read it, place it in context, decide whether it belongs, and often explain why it does not.

The “add your name to the README” wave made that painfully clear. In February 2024, Express contributors were openly discussing how to curb spammy README.md pull requests from new contributors because they were creating noise and extra moderation work rather than meaningful progress.

That gives you a better test than “Can I open a PR?”

Ask instead:

Does this change solve a real problem the project actually has?
Can I explain why this approach makes sense here?
Have I made it easy for someone else to trust what I’m proposing?

If the answer is not yet “yes”, you probably need more context, not more code.

Open-source projects do not just have technical architecture. They have social architecture too.

There is usually a pattern to how decisions get made, how questions get answered, what gets prioritised, and what gets pushed back on. If you miss that layer, you can write a technically decent patch and still make a poor contribution.

Start with the obvious documents, but treat them as operating instructions rather than admin clutter. Read the README, contribution guide, issue templates, pull request template, code of conduct, and governance notes. Those pages tell you what kind of help the project wants, where different kinds of discussion belong, and what behaviour creates friction.

Then look past the documents and study the project in motion.

Read a few open issues from start to finish. Read a few recently merged pull requests. Then read a few that were closed without merging. That comparison is often more useful than any generic open-source advice because it shows you how this project behaves in practice.

You will start to notice patterns.

Maybe small, scoped changes land faster than broad clean-ups.
Maybe maintainers care a lot about tests.
Maybe they want discussion before implementation on larger changes.
Maybe support questions belong somewhere else entirely.
Maybe the project values consistency more than cleverness.

That is the social architecture. It tells you what “helpful” means here, not in theory.

It also changes how you ask questions.

A weak question hands your confusion to someone else.
A strong question shows the thinking you have already done.

“Can someone explain this whole module?” is a weak question.

“I traced this behaviour to this file, and I think this branch is why the bug appears, but I’m not sure whether that behaviour is intentional” is a strong one.

The second question gives someone something concrete to respond to. It narrows uncertainty instead of exporting it.

That is the habit you want.

Find the project’s pressure points

If the social architecture tells you how the project behaves, the pressure points tell you why.

From the outside, an open-source project can look like a simple list of issues and pull requests. From the inside, it is usually a bundle of maintenance costs competing for limited attention. Bugs need reproducing. Pull requests need review. Regressions need testing. Releases need preparing. Duplicate reports need closing. Docs need updating.

That is why project behaviour can look harsher than it really is.

A slow reply is not always dismissive.
A short reply is not always rude.
A closed issue is not always a judgment on you.

Sometimes it just means the project has learned to protect scarce attention.

If you want to be useful, figure out where the pressure actually is.

If the issue tracker is full of vague reports, a careful reproduction is useful.
If pull requests keep stalling on tests, test work is useful.
If the same confusion keeps appearing in issues, a precise docs fix is useful.
If maintainers keep redirecting people to the same answer, someone who reads first is already easier to work with.

This is where many contributors go wrong. They choose work that looks like contribution instead of work that relieves pressure.

Maintainers do not need more contribution-shaped activity. They need fewer unknowns, fewer unnecessary reviews, and fewer loose ends.

That is the day-to-day reality you need to acquaint yourself with before you try to change anything.

Read the codebase like an investigator

A lot of new contributors open a repository and try to understand the whole thing.

That is usually wasted effort.

You do not need total understanding. You need enough local understanding to make a trustworthy change.

The best way to do that is to read the codebase like an investigator, not a tourist. Start from a concrete question and follow the path that question takes through the system.

If you are looking at a bug, start where the bug appears and trace inward.
If you are looking at a feature, start where the user encounters it and follow the flow.
If you are looking at an error message, search for the exact text and find where it originates.

This is much more effective than browsing files until something feels familiar.

Look for landmarks. Where is the setup logic? Where are the tests? Which modules appear repeatedly in recent pull requests? Are there architecture notes? Are there directories whose names keep coming up in issue discussions?

Those clues tell you where the important paths are.

Tests are especially valuable here. They tell you what the project thinks “correct” means. They also show you how contributors are expected to express changes. If you want to understand how a piece of behaviour is meant to work, the test suite often explains it more clearly than the implementation.

Past pull requests help too. Find a recent change in the same part of the codebase. Read the diff, then read the review comments. You will often learn more from what had to be clarified, shrunk, or reworked than from the final code alone.

The goal is not to read widely. It is to become specific.

When you can say, “The bug starts here, seems to flow through these two modules, and is probably covered by this test,” you are in a much better position to contribute.

Not because you know the whole codebase, but because you know the part you are touching well enough to make your reasoning visible.

Use AI to compress learning, not responsibility

AI is now part of open-source contribution whether people like it or not. The real question is not whether you use it. The question is whether you use it in a way that makes your contribution better or just faster-looking.

A simple rule cuts through most of the noise:

Use AI to compress learning. Do not use it to compress responsibility.

That means AI can help you understand a pattern, compare approaches, summarise documentation, suggest cases you might want to test, or help you phrase a question more clearly before you post it. CPython’s contributor guide allows this kind of use, while making clear that contributors remain responsible for the usefulness and quality of what they submit. It also says maintainers may close issues and pull requests that are not useful or productive, including ones that are fully generated by AI.

What AI should not do is become your proxy.

NumPy’s AI policy is unusually clear: contributors are responsible for any code they submit, whether written manually or generated by AI; they must understand it and be able to explain it. NumPy also says it will reject pull requests it deems “AI slop” and tells contributors not to use AI to automatically generate normal project communication such as issue descriptions, pull request descriptions, or comments.

That is the right standard because maintainers are not reviewing for local plausibility. They are reviewing for fit.

Does this solve the real problem?
Does it match the project’s conventions?
Does it introduce churn for little benefit?
Can the author explain why this approach makes sense here?

AI is often decent at producing plausible-looking code. Plausible-looking code is not the same thing as a good contribution.

So use AI privately if it helps you think. But do not let it speak for you in public, and do not submit work you cannot defend line by line.

If you would struggle to answer “Why this change?” in a review, AI has not saved you time. It has just delayed the cost until someone else has to pay it.

Choose work that removes ambiguity

Once you have context, understand the project’s pressure points, and know your way around the relevant code, you still do not need to start with a grand fix.

Start with the kind of contribution that removes ambiguity.

That is the sweet spot for first contributions because ambiguity is what drains maintainers. They are constantly trying to work out whether a report is reproducible, whether a bug is current, whether a change is safe, whether a proposed fix matches the project’s direction, and whether a contributor understands what they are touching.

The best early contributions make those answers easier.

A strong first contribution might be:

a bug report with exact reproduction steps
a focused test that proves a failure clearly
a docs fix that removes a common point of confusion
a small patch in an area you have already traced properly and can explain with confidence
a careful confirmation that an issue still exists in a current version

What matters is not whether the change is glamorous. It is whether the thinking is legible.

That is a better filter than “good first issue”, which can be useful but often hides the real question. The real question is not “Is this easy?” It is “Can I understand this fully enough to make a change that is needed, correct, and easy to trust?”

That is how you choose a first contribution that actually helps.

Make it easier to trust you

Good open-source contribution starts earlier than code.

It starts when you learn how a project makes decisions, where it is under pressure, and what kind of work reduces uncertainty rather than adding more of it. It starts when you read the codebase with a concrete question in mind. And it starts when you use AI, if you use it at all, as a tool for understanding rather than a way to outsource judgment.

That is the standard worth aiming for.

Not “I opened a pull request.”
Not “I got something merged.”
But: I made this project easier to work on.

That is what maintainers notice. That is what builds trust. And that is what turns you from someone showing up in the notifications into someone the project is genuinely glad to see.