engineeringcommunication
Open Source Contributing Guide
Write open source contributing guides — with setup instructions, code standards, PR processes, issue templates, and community guidelines that lower the barrier for new contributors.
open-sourcecontributingcommunitypull-requestsguidelines
Works well with agents
Works well with skills
$ npx skills add The-AI-Directory-Company/(…) --skill open-source-contributing-guideopen-source-contributing-guide/
SKILL.md
Markdown
| 1 | |
| 2 | # Open Source Contributing Guide |
| 3 | |
| 4 | ## Before you start |
| 5 | |
| 6 | Gather the following from the user. If anything is missing, ask before proceeding: |
| 7 | |
| 8 | 1. **What is the project?** (Name, language, framework, repo URL) |
| 9 | 2. **What is the project's maturity?** (New, established with existing norms, large ecosystem) |
| 10 | 3. **What contributions are welcome?** (Code, docs, tests, design, translations, triage) |
| 11 | 4. **What is the tech stack?** (Languages, build tools, test frameworks, CI/CD) |
| 12 | 5. **What is the governance model?** (Solo maintainer, core team, foundation-backed) |
| 13 | 6. **What license does the project use?** (MIT, Apache 2.0, GPL, etc.) |
| 14 | |
| 15 | If the user says "we just need a CONTRIBUTING.md," clarify: a contributing guide without working setup instructions and clear PR expectations creates frustrated contributors who never return. |
| 16 | |
| 17 | ## Contributing guide template |
| 18 | |
| 19 | ### 1. Welcome and Orientation |
| 20 | |
| 21 | ```markdown |
| 22 | # Contributing to [Project Name] |
| 23 | |
| 24 | ## Ways to Contribute |
| 25 | |
| 26 | - **Report bugs** — File an issue with a reproduction case |
| 27 | - **Fix bugs** — Pick up issues labeled `good first issue` or `help wanted` |
| 28 | - **Add features** — Discuss in an issue before starting work |
| 29 | - **Improve docs** — Fix typos, add examples, clarify explanations |
| 30 | - **Write tests** — Increase coverage, add edge cases |
| 31 | - **Review PRs** — Constructive feedback on open pull requests |
| 32 | |
| 33 | ## Before You Start |
| 34 | |
| 35 | 1. Read our [Code of Conduct](CODE_OF_CONDUCT.md) |
| 36 | 2. Check [existing issues](link) to avoid duplicate work |
| 37 | 3. For features or large changes, open an issue first |
| 38 | ``` |
| 39 | |
| 40 | Keep this section short. Contributors decide within 60 seconds whether to keep reading. |
| 41 | |
| 42 | ### 2. Development Setup |
| 43 | |
| 44 | Write setup instructions that work on a fresh machine. Include prerequisites (language version, package manager), fork-and-clone steps, dependency installation, environment setup, and a command to run the test suite that verifies the setup works. |
| 45 | |
| 46 | Include a troubleshooting table for known setup issues (common error messages with specific fixes). Every setup problem a contributor solves alone is a contributor who almost left. |
| 47 | |
| 48 | ### 3. Code Standards |
| 49 | |
| 50 | Define standards that tooling enforces: |
| 51 | |
| 52 | ``` |
| 53 | Automated Checks (CI enforces): |
| 54 | - Linting: [linter] — run `[lint command]` locally |
| 55 | - Formatting: [formatter] — run `[format command]` to auto-fix |
| 56 | - Type checking: [type checker] — run `[type check command]` |
| 57 | - Tests: run `[test command]` |
| 58 | ``` |
| 59 | |
| 60 | Specify commit message format (recommend Conventional Commits): `<type>(<scope>): <description>`. Types: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`. Include 2-3 concrete examples. |
| 61 | |
| 62 | If a rule is important enough to write down, it is important enough to enforce with a linter or pre-commit hook. |
| 63 | |
| 64 | ### 4. Pull Request Process |
| 65 | |
| 66 | ``` |
| 67 | Before opening a PR: |
| 68 | - [ ] Branch is up to date with `main` |
| 69 | - [ ] All tests pass locally |
| 70 | - [ ] Linting passes |
| 71 | - [ ] Tests added for new functionality |
| 72 | - [ ] Documentation updated if behavior changed |
| 73 | |
| 74 | PR guidelines: |
| 75 | - One logical change per PR |
| 76 | - Include what changed, why, how to test, and link to related issue |
| 77 | - PR size guide: <100 lines (fast review), 100-500 (standard), 500+ (discuss first) |
| 78 | |
| 79 | Review process: |
| 80 | - [N] maintainer approval(s) required |
| 81 | - CI must pass before merge |
| 82 | - Review within [X] business days |
| 83 | ``` |
| 84 | |
| 85 | Set explicit review time expectations. Contributors who wait 3 weeks for a review do not come back. |
| 86 | |
| 87 | ### 5. Issue Guidelines |
| 88 | |
| 89 | **Bug reports** must include: environment details, numbered reproduction steps, expected vs. actual behavior, and a minimal reproduction case. |
| 90 | |
| 91 | **Feature requests** must include: problem statement (not solution), proposed approach, alternatives considered, and who benefits. |
| 92 | |
| 93 | Define issue labels: `good first issue` (new contributors), `help wanted` (outside contributions welcome), `bug`, `enhancement`, `needs triage`. |
| 94 | |
| 95 | ### 6. Community |
| 96 | |
| 97 | List communication channels (GitHub Issues, chat platform, forum/discussions) with expected response times. Document how contributors are recognized (contributors page, release notes). |
| 98 | |
| 99 | ## Quality checklist |
| 100 | |
| 101 | - [ ] Setup instructions work on a fresh machine — tested, not assumed |
| 102 | - [ ] Every code standard is enforced by tooling or explicitly marked as convention |
| 103 | - [ ] PR process includes size guidelines and explicit review time commitments |
| 104 | - [ ] Issue templates cover bug reports and feature requests |
| 105 | - [ ] Communication channels listed with expected response times |
| 106 | - [ ] Written for someone who has never seen the codebase |
| 107 | - [ ] Troubleshooting section covers known setup pain points |
| 108 | - [ ] Guide links to the Code of Conduct |
| 109 | |
| 110 | ## Common mistakes |
| 111 | |
| 112 | - **Setup that only works on the maintainer's machine.** Test on a fresh environment. "Works for me" loses contributors. |
| 113 | - **Unclear PR scope.** Without size guidelines, contributors submit 2,000-line PRs nobody can review. |
| 114 | - **No response time commitments.** Contributors who wait weeks for review do not return. |
| 115 | - **Code of Conduct without enforcement.** A CoC never referenced or enforced is performative. |
| 116 | - **Missing "good first issue" labels.** New contributors need well-scoped starter issues as entry points. |
| 117 | - **Writing for experts.** The guide is for newcomers. Avoid internal terminology and assumed context. |
| 118 |