Contributing to open source

Contributing to open source is one of the most instructive ways of becoming a better programmer — and one of the easiest to get wrong.

The order that works:

#	The step
1	Read CONTRIBUTING.md — it nearly always exists and answers most questions
2	Search the existing issues and PRs — somebody may already have tried
3	Open an issue first unless it is a trivial fix
4	Wait for a response before writing code
5	Write a failing test
6	Make the smallest change that makes the test pass
7	Open a PR explaining why, not just what

Steps 3 and 4 are the ones most often skipped, and they save the most time. A large PR nobody asked for is often rejected — not because the code is bad but because the direction was not agreed.

Start small. A documentation error, a missing test case, a clarified error message. That teaches you the process without risking a week's work.

What makes a PR easy to review:

The property	Why
One thing at a time	a PR fixing three things is three times harder to review
A test showing the fault	the reviewer can verify that the problem existed
A small diff	under 200 lines is often reviewed the same day; 2 000 lines sit for weeks
A description with the why	the code shows what; the description should show why
The project's code style	run their formatter and linter before you send it
No unrelated changes	reformatting the whole file hides your actual change

The last is a classic: an editor that reformats on save turns a two-line change into a 400-line diff, and the reviewer can no longer see what you actually did.

Licences and law. Check the project's licence before you contribute. Some require you to sign a CLA (contributor licence agreement) or to certify the origin with a Signed-off-by line (DCO). If you contribute during working hours: check what your employment says about copyright in code.

AI-generated code in contributions is a question every project handles differently. Several large projects now require you to state whether code was generated with AI tools, and some forbid it. Check the policy, and be open — it is simpler than being asked afterwards.

Receiving a review. The comments are about the code, not about you. Three attitudes that work:

1. Ask if you do not understand instead of guessing what they mean.
2. Do not agree automatically — if you have a reason, explain it; change your mind if the reason does not hold.
3. Say thank you and move on. The reviewer is spending their time on your contribution.

If the PR is not accepted it is not wasted. You have learnt the codebase, the process and something about what is required. Many long-standing contributors started with a rejected PR.

Maintaining a project of your own is the other side: write a CONTRIBUTING.md, label issues with good first issue, answer within a reasonable time even when the answer is no, and be clear about what the project is not going to do. The last saves the most time for everybody.

Make your first contribution this week. A concrete plan, about three hours.

Step 1 — find a project (30 min).

• Something you use. That is the most important criterion: you understand what it is supposed to do.
• Check that it is active: the latest commit within a month, PRs that get answers.
• Search for label:"good first issue" in their issue list.

Step 2 — choose a task (20 min).

• Documentation that is wrong or unclear — the best start.
• An error message that does not help.
• A missing test case.
• Avoid: architecture changes, performance optimisations, «I think you ought to».

Step 3 — agree the direction (10 min + waiting).

• Comment on the issue: «I would like to take this. My plan is X. Does that sound reasonable?»
• Wait for an answer. If none comes within a week, choose another project.

Step 4 — do the work (60 min).

• Fork, clone, create a branch with a descriptive name.
• Run the test suite first — does it work before you have changed anything?
• Write the failing test.
• Make the change.
• Run their formatter and linter.

Step 5 — send it (30 min).

• Write a description: what the problem was, how you solved it, how to verify it.
• Link to the issue.
• Check that the CI is green.

Step 6 — respond (ongoing).

• Answer the comments within a few days.
• Change what should be changed, justify what you keep.

What you get out of it, whatever the outcome: you have read a real codebase, understood a real process and written code somebody else reviewed. The last is hard to get any other way.