ContributingCopy Anchor Link

Contributing is a social skill with a technical payload. The code is rarely the hard part; knowing what the project wants, in the shape it wants it, and waiting for review without nagging, is what gets a patch merged.

1. Before you write anythingCopy Anchor Link

1. Read README.md, CONTRIBUTING.md and CODE_OF_CONDUCT.md. Most rejected PRs fail here.
2. Get the project running and run its tests. If you cannot build it, you cannot review your own change.
3. Check the licence and sign-off requirement: DCO (git commit -s) or CLA.
4. Look at recently merged PRs to learn the house style.

If your employer's contract assigns IP to them, you may need written permission to contribute, or to contribute under a corporate CLA. Ask before you push, not after.

2. Finding workCopy Anchor Link

• good first issue, help wanted, documentation labels — the maintainer has already decided these are safe to hand out.
• Fix a problem you actually hit. You can test it, and you can describe it precisely.
• Improve an error message, a doc example, or a test. Low risk, high signal.
• Do not open large refactors, formatting sweeps or dependency bumps unannounced — open an issue and ask first.

3. Filing a good issueCopy Anchor Link

The whole job is to make reproduction cheap for someone who has never met you.

Environment
- project version: 2.4.1
- runtime / OS: Python 3.12.4, Ubuntu 24.04
- installed via: pip

What I did
1. `mytool convert --input a.json`
2. `mytool convert --input b.json`

Expected
Two output files.

Actual
Second run raises `KeyError: 'schema'` at converter.py:142.

Minimal reproduction
from mytool import convert
convert({"schema": None})   # fails
convert({"schema": "v1"})   # works

Logs
(full traceback, not a screenshot)

• Search first. Commenting "me too" is more useful than a duplicate.
• Include versions. "Latest" is not a version.
• Paste text, not screenshots of text.
• Offer to implement it — and wait for a reply before starting.

4. The pull requestCopy Anchor Link

# Typical fork-based workflow
git clone https://github.com/you/project.git
cd project
git switch -c fix/schema-keyerror

# ... edit, then commit with sign-off if the project uses DCO
git add -p
git commit -s -m "fix(converter): handle missing schema key

Previously converter.py:142 assumed 'schema' was present.
Fall back to the default schema and warn instead.

Fixes #1234"

# rebase onto current main before pushing
git fetch upstream && git rebase upstream/main
git push -u origin fix/schema-keyerror

• Small and single-purpose. One logical change per PR. 20 lines gets reviewed in a day; 2,000 lines gets reviewed never.
• Explain why in the description. Link the issue with Fixes #1234.
• Add or update tests. A bug fix without a regression test will regress.
• Update docs and CHANGELOG in the same PR if the project keeps them in-tree.
• Conventional commit messages (fix:, feat:, docs:, chore:) if the project automates SemVer or changelogs.
• Make CI green before asking for review.
• Do not force-push after review starts — it destroys the review thread. Add fixup commits and squash at merge.

5. Surviving reviewCopy Anchor Link

• Review comments are about the code, not about you.
• Reply to every comment, even if only "done". Unanswered comments stall merges.
• If you disagree, argue the trade-off with evidence (benchmark, failing case, upstream reference).
• Maintainers are usually unpaid and reviewing in their own time. A polite ping after a week or two is reasonable; daily pings are not.
• If the PR goes stale for months, rebase and ask whether it is still wanted.

6. Non-code contributionsCopy Anchor Link

Usually the fastest route to becoming a trusted contributor, because the review burden is lower.

• Documentation and examples — the most common real gap in any project.
• Issue triage — reproduce bugs, ask for versions, close duplicates.
• Translation / localisation — whole ecosystems run on this.
• Answering questions in forums, Discord, Stack Overflow.
• Design, UX, accessibility — rarely volunteered, always needed.
• Security research — privately, through SECURITY.md.
• Funding — sponsorship, or your employer's foundation membership.

7. Legal mechanicsCopy Anchor Link

8. The maintainer's sideCopy Anchor Link

If you run a project, the goal is to make contributing cheap and predictable.

• Issue templates and CODEOWNERS so reports arrive complete and land on the right desk.
• Label taxonomy — good first issue, bug, needs-repro, blocked — and a stated triage cadence.
• Automate the boring rejections: CI, linters, DCO bot, licence checks. Humans should only review what a machine cannot decide.
• Write the review SLA you can keep ("first response within 5 working days"). Under-promise.
• Delegate by directory. Subsystem owners scale; a central bottleneck does not.
• Enforce the Code of Conduct visibly. Nothing kills diversity faster than a known jerk nobody acts on.
• Protect your own time: office hours, a public roadmap, and a documented "we do not accept X" policy.

9. Where projects liveCopy Anchor Link

See also: Governance · Foundations · Licenses · Business models