OSS Contribution Best Practices

Open Source Contribution Best Practices

Reference: Based on opensource.guide

This skill is the index. The detail topics live in two sibling skills that load on demand:

• pr-etiquette — responding to code review feedback, writing PR descriptions, dormant-PR follow-up cadence, PR quality checklist, communication etiquette.
• contribution-ethics — AI attribution rules, AI-tell avoidance in maintainer-visible writing, when to defer to a human.

Both are linked below. Use this file for the universal rules that apply to every contribution regardless of stage; jump to the sibling skills when you're at a specific stage in the cycle.

Core Principles

Be a good open source citizen:

1. Respect maintainers' time — they're often unpaid volunteers
2. Read contribution guidelines before contributing
3. Communicate clearly and professionally
4. Be patient — open source moves at its own pace
5. Give back to the community when you can

Minimal Diff Discipline

Every line in a PR diff must be directly related to the issue being fixed. Unrelated formatting changes (whitespace, quote style, trailing commas, import reordering, line breaks) make diffs noisy, harder to review, and signal carelessness. Maintainers will flag or reject PRs with formatting bloat.

Rules:

1. Only touch lines the fix requires. Don't reorder imports, change quote styles, fix whitespace, or add trailing commas in existing code — unless those changes are part of the fix itself.
2. Scope formatter output. If the repo's formatter must be run (e.g., CI requires it), review the formatter's changes afterward. Use git diff to identify formatting-only changes. Use git checkout -- {files} only for files where ALL changes are formatting-only. For files with mixed changes, use targeted edits to surgically remove formatting hunks. (In interactive terminal contexts, git add -p can also be used for hunk-level staging.)
3. Match the repo's style, don't impose your own. If the repo uses single quotes, use single quotes in your new code. If it uses tabs, use tabs. Never convert existing style to a different one.