Open Source Contribution Path

Most rejected first-time pull requests aren't rejected for bad code — they're rejected because the contributor skipped a step that would have told them the maintainer didn't want that change, in that shape, at all. This lesson covers the path from "I want to contribute" to a merged pull request, and the etiquette that makes a maintainer want to work with you again.

Finding Something To Work On

• Labels meant for newcomers — good first issue and help wanted are the closest thing to an explicit invitation; a maintainer tagged that issue as scoped and approachable for someone new to the codebase.
• Documentation gaps — a confusing install step, a missing example, an outdated code snippet — are lower-risk first contributions than logic changes: smaller diffs, easier to review, and the contributor doesn't need deep familiarity with the codebase's internals to get it right.
• A bug you hit yourself while using the project — you already have a reproduction case and a concrete understanding of the problem, which is most of the work of a good bug report already done.
• What NOT to start with: a large refactor, a new major feature, or "I rewrote this in a style I prefer" — all high-effort, high-risk-of-rejection first contributions, because they require the maintainer to evaluate a large diff against project direction they haven't discussed with you yet.

Read Before You Write

Before opening an issue or PR, check for a CONTRIBUTING.md file — many projects document exactly how they want contributions made: coding style, test requirements, commit message format, whether a Contributor License Agreement (CLA) or Developer Certificate of Origin (DCO) sign-off is required. Skipping this is the single most avoidable cause of a frustrating first contribution — the rules were often written down precisely because the maintainer got tired of explaining them in every PR review.

Also check open and recently closed issues/PRs for the same problem — someone may have already reported it, fixed it, or explained why it's not a bug. Duplicating effort the project has already resolved is a common, easily-avoided first mistake.

Discuss Before You Build (For Anything Nontrivial)

For a typo fix or small doc correction, just send the PR. For anything larger — a new feature, a behavior change, a nontrivial refactor — open an issue first and describe what you want to do before writing the code. This is not bureaucracy; it's the step that prevents wasted work. A maintainer might already have a different design in mind, might have rejected this exact idea before for a reason not visible from outside, or might simply not want the added maintenance surface. Finding that out before you've written 400 lines is much better for both of you than after.

The Standard Workflow

1. Fork the repository to your own account (or, if you have write access, create a branch directly).
2. Branch from the project's default branch, named descriptively.
3. Make the smallest change that solves the discussed problem. Resist the urge to also fix unrelated things you noticed along the way — a focused diff is faster to review and less likely to be rejected for scope creep; file a separate issue for the unrelated problem instead.
4. Match the project's existing style and conventions — indentation, naming, test structure — even if you'd personally do it differently. Consistency with the existing codebase matters more than your personal preference in someone else's project.
5. Add or update tests covering the change, following the project's existing test patterns.
6. Write a clear PR description: what changed, why, and a link to the issue discussion if one exists.
7. Respond to review promptly and without defensiveness. Maintainer feedback on a first PR is usually about fit with the project's conventions, not a judgment of your ability — treat requested changes as normal, not as a sign the contribution was unwelcome.

Licensing And Legal Signals

Every contribution you send becomes part of a codebase under that project's license — understand what you're agreeing to. Some projects require a CLA (a separate legal agreement) or DCO sign-off (git commit -s, certifying you wrote the code and have the right to submit it under the project's license) before accepting contributions; check CONTRIBUTING.md for this requirement before your PR is blocked on it late. Never submit code you copied from a differently-licensed source without checking compatibility — this is the contributor-side mirror of the license-evaluation care covered when consuming dependencies.

What Makes A First Contribution Get Merged

• Scope matches what was discussed — no surprise extra changes bundled in.
• Tests exist and pass, following the project's own conventions for how tests are written.
• The diff is readable — a reviewer should be able to understand what changed and why from the diff and description alone, without needing a call to explain it.
• Response to feedback is fast and non-defensive — a maintainer reviewing volunteer contributions in their spare time is far more likely to keep engaging with a contributor who responds promptly and adjusts, versus one who argues every point or goes silent for weeks.

Failure Modes

The most common failure is a large, unrequested rewrite as a first contribution — sent with good intentions, but forcing the maintainer to evaluate an unplanned, high-risk change against project direction never discussed, which is why it's rejected regardless of code quality.

The second is skipping CONTRIBUTING.md and getting the basics wrong — wrong branch, missing tests, wrong commit format — creating review friction that has nothing to do with the substance of the change and everything to do with skippable process.

The third is taking review feedback personally and disengaging — going quiet or arguing defensively after requested changes, which (from the maintainer's side) looks identical to abandoning the contribution, and often ends the same way: the PR goes stale and gets closed.

The fourth is not checking for duplicate or prior-rejected work, resubmitting something the project already declined, without engaging with the reason it was declined the first time.

Review Checklist

• The contribution's scope matches what was discussed in an issue (for anything beyond a trivial fix), with no unrelated changes bundled in.
• CONTRIBUTING.md conventions (style, tests, commit format, CLA/DCO) were checked and followed before the PR was opened.
• Tests exist for the change and follow the project's own test patterns.
• The PR description explains what and why clearly enough that a reviewer doesn't need external context.
• Prior issues/PRs were checked to avoid duplicating already-resolved or already-declined work.
• The contributor's response plan to review feedback is prompt engagement, not silence or defensiveness.

What You Should Be Able To Do

After this lesson, you should be able to find an appropriately-scoped first issue, read and follow a project's contribution conventions, discuss a nontrivial change before building it, submit a focused pull request with tests, and respond to maintainer feedback in a way that keeps the collaboration working rather than ending it.

This covers exactly the five things the exercise asked for, each as a short, actionable rule rather than an essay: when to discuss first, the one-change-per-PR scope rule, a concrete test requirement tied to the actual test directory, an automated style tool instead of prose formatting rules (removing style as a subjective review point entirely), and a stated response-time expectation that heads off the "silence means rejection" misunderstanding the article warns about. Pointing at `composer cs-fix` instead of writing out style rules is deliberate — it turns a discussion into a command a contributor can run themselves before ever opening the PR.