Projects with comprehensive contribution guides receive 3x more pull requests than those without, according to GitHub's Open Source Survey. Below: the complete CONTRIBUTING.md template you can copy, plus issue templates and PR checklists that work.
The Complete CONTRIBUTING.md Template (Copy-Paste)
# Contributing to [Project Name] First off, thank you for considering contributing to [Project Name]! It's people like you that make [Project Name] such a great tool. ## Table of Contents - [Code of Conduct](#code-of-conduct) - [How Can I Contribute?](#how-can-i-contribute) - [Development Setup](#development-setup) - [Pull Request Process](#pull-request-process) - [Style Guide](#style-guide) - [Community](#community) ## Code of Conduct This project and everyone participating in it is governed by our [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. ## How Can I Contribute? ### 🐛 Reporting Bugs Before creating bug reports, please check existing issues to avoid duplicates. When you create a bug report, include as many details as possible using our [bug report template](.github/ISSUE_TEMPLATE/bug_report.md). **Great bug reports include:** - A clear, descriptive title - Steps to reproduce the behavior - Expected behavior vs actual behavior - Screenshots (if applicable) - Environment details (OS, browser, version) ### 💡 Suggesting Features Feature requests are welcome! Please use our [feature request template](.github/ISSUE_TEMPLATE/feature_request.md). **Great feature requests include:** - Clear problem statement: "I'm frustrated when..." - Proposed solution - Alternative solutions you've considered - Additional context ### 📝 Improving Documentation Documentation improvements are always welcome! This includes: - Fixing typos - Adding examples - Clarifying confusing sections - Translating documentation ### 🔧 Submitting Code Look for issues labeled `good first issue` or `help wanted` for great places to start. ## Development Setup ### Prerequisites - Node.js 18+ - npm 9+ or yarn 1.22+ - Git ### Getting Started ```bash # 1. Fork the repository on GitHub # 2. Clone your fork locally git clone https://github.com/YOUR_USERNAME/[project-name].git cd [project-name] # 3. Add upstream remote git remote add upstream https://github.com/ORIGINAL_OWNER/[project-name].git # 4. Install dependencies npm install # 5. Create a branch for your changes git checkout -b feature/your-feature-name # 6. Start development server npm run dev # 7. Run tests to verify setup npm test ``` ### Common Commands | Command | Description | |---------|-------------| | `npm run dev` | Start development server | | `npm test` | Run test suite | | `npm run lint` | Check code style | | `npm run format` | Auto-format code | | `npm run build` | Build for production | ## Pull Request Process ### Before Submitting 1. **Update your branch** with the latest upstream changes: ```bash git fetch upstream git rebase upstream/main ``` 2. **Run the full test suite** and ensure all tests pass: ```bash npm test ``` 3. **Run linting** and fix any issues: ```bash npm run lint ``` 4. **Update documentation** if you've changed APIs or added features. ### Submitting 1. Push your branch to your fork: ```bash git push origin feature/your-feature-name ``` 2. Open a Pull Request against the `main` branch. 3. Fill out the PR template completely. 4. Wait for review. We aim to respond within 7 days. ### PR Checklist - [ ] My code follows the project's style guidelines - [ ] I have performed a self-review of my own code - [ ] I have commented my code, particularly in hard-to-understand areas - [ ] I have made corresponding changes to the documentation - [ ] My changes generate no new warnings - [ ] I have added tests that prove my fix is effective or that my feature works - [ ] New and existing unit tests pass locally with my changes ## Style Guide ### Commit Messages We follow [Conventional Commits](https://conventionalcommits.org/): ```( ): [optional body] [optional footer] ``` **Types:** - `feat`: New feature - `fix`: Bug fix - `docs`: Documentation only - `style`: Formatting, missing semicolons, etc. - `refactor`: Code change that neither fixes a bug nor adds a feature - `test`: Adding missing tests - `chore`: Maintenance tasks **Examples:** ``` feat(auth): add OAuth2 support fix(api): handle null response from payment provider docs(readme): update installation instructions ``` ### Code Style - Use Prettier for formatting (config included) - Use ESLint for linting (config included) - Run `npm run format` before committing - Write self-documenting code with meaningful variable names - Add JSDoc comments for public APIs ### Testing - All new features must include tests - Bug fixes should include regression tests - Aim for >80% code coverage on new code - Tests should be deterministic (no flaky tests) ## Community - [Discord](https://discord.gg/[invite-code]) - Chat with maintainers - [Discussions](https://github.com/[owner]/[repo]/discussions) - Ask questions - [Twitter](https://twitter.com/[handle]) - Follow for updates ## Recognition Contributors are added to our [CONTRIBUTORS.md](CONTRIBUTORS.md) file and mentioned in release notes for significant contributions. --- Thank you for contributing! 🎉
Issue Template: Bug Report
Save this as .github/ISSUE_TEMPLATE/bug_report.md:
--- name: Bug Report about: Create a report to help us improve title: '[BUG] ' labels: 'bug, needs-triage' assignees: '' --- ## Describe the Bug A clear and concise description of what the bug is. ## To Reproduce Steps to reproduce the behavior: 1. Go to '...' 2. Click on '...' 3. Scroll down to '...' 4. See error ## Expected Behavior A clear description of what you expected to happen. ## Actual Behavior What actually happened instead. ## Screenshots If applicable, add screenshots to help explain your problem. ## Environment - OS: [e.g., macOS 14.0, Windows 11, Ubuntu 22.04] - Browser: [e.g., Chrome 120, Firefox 121] - Version: [e.g., 2.1.0] - Node.js version: [e.g., 18.19.0] ## Additional Context Add any other context about the problem here. ## Possible Solution (optional) If you have suggestions on how to fix the bug.
Issue Template: Feature Request
Save this as .github/ISSUE_TEMPLATE/feature_request.md:
--- name: Feature Request about: Suggest an idea for this project title: '[FEATURE] ' labels: 'enhancement, needs-triage' assignees: '' --- ## Problem Statement **Is your feature request related to a problem?** A clear description of what the problem is. Example: "I'm always frustrated when [...]" ## Proposed Solution A clear description of what you want to happen. ## Alternative Solutions Describe any alternative solutions or features you've considered. ## Use Cases Describe specific use cases for this feature: 1. As a [type of user], I want [goal] so that [benefit] 2. ... ## Additional Context - Add mockups, diagrams, or examples - Links to similar features in other projects - Any other context ## Willing to Contribute? - [ ] I'm willing to submit a PR for this feature - [ ] I can help test this feature - [ ] I can help document this feature
Pull Request Template
Save this as .github/PULL_REQUEST_TEMPLATE.md:
## Description ## Related Issue Fixes #(issue number) ## Type of Change - [ ] 🐛 Bug fix (non-breaking change that fixes an issue) - [ ] ✨ New feature (non-breaking change that adds functionality) - [ ] 💥 Breaking change (fix or feature that would cause existing functionality to change) - [ ] 📝 Documentation update - [ ] 🧹 Code refactor (no functional changes) - [ ] ✅ Test update ## How Has This Been Tested? - [ ] Unit tests - [ ] Integration tests - [ ] Manual testing **Test configuration:** - OS: - Node version: ## Screenshots (if applicable) ## Checklist - [ ] My code follows the project's style guidelines - [ ] I have performed a self-review of my own code - [ ] I have commented my code in hard-to-understand areas - [ ] I have updated the documentation - [ ] My changes generate no new warnings - [ ] I have added tests that prove my fix/feature works - [ ] New and existing tests pass locally - [ ] Any dependent changes have been merged and published ## Additional Notes
Section-by-Section Breakdown
| Section | Purpose | Must Include |
|---|---|---|
| Welcome Message | Make contributors feel valued | Thank you + positive tone |
| Code of Conduct | Set community standards | Link to CoC file |
| Types of Contributions | Show all ways to help | Code, docs, bugs, features, translations |
| Development Setup | Get contributors running locally | Prerequisites + step-by-step commands |
| Workflow | Explain branch/commit process | Branch naming, commit format |
| PR Process | Guide submission | Checklist + expected timeline |
| Style Guide | Ensure consistent code | Linting, formatting, testing rules |
| Recognition | Motivate contributors | How contributors are credited |
Good First Issue Labels
Create these labels to help new contributors find appropriate issues:
| Label | Description | Color (Hex) |
|---|---|---|
| good first issue | Good for newcomers | #7057ff |
| help wanted | Extra attention needed | #008672 |
| documentation | Improvements or additions to docs | #0075ca |
| beginner friendly | Low complexity, good starting point | #c5def5 |
| up for grabs | Open for anyone to work on | #fbca04 |
Contribution Guide Checklist
Score your guide (1 point each):
| Element | Points |
|---|---|
| Welcoming opening message | /1 |
| Code of conduct linked | /1 |
| Multiple contribution types listed | /1 |
| Development setup with commands | /1 |
| Prerequisites clearly stated | /1 |
| PR process documented | /1 |
| Commit message format specified | /1 |
| Testing requirements explained | /1 |
| Issue templates provided | /1 |
| PR template provided | /1 |
Score interpretation: 8-10 = Excellent; 6-7 = Good; 4-5 = Needs work; <4 = Major gaps
Frequently Asked Questions
How long should a CONTRIBUTING.md be?
500-1,500 words is ideal. Cover essentials without overwhelming. Link to detailed docs for complex topics (detailed API guidelines, architecture decisions). New contributors should be able to start contributing within 30 minutes of reading your guide.
Should I require issue discussion before PRs?
Yes for features, optional for bug fixes. Requiring issues for features prevents wasted effort on unwanted changes. For simple bug fixes, direct PRs are fine. State your preference clearly: "Please open an issue before working on new features."
How quickly should maintainers respond to PRs?
Set expectations you can meet—7 days is standard. "We aim to respond within 7 days" is realistic for most projects. If you're slower, say so honestly. Fast response times retain contributors. Silence kills contribution momentum.
What if a contributor submits a bad PR?
Be kind, be specific, be helpful. Never: "This is wrong." Always: "Thanks for contributing! A few suggestions: [specific feedback with code examples]." First-time contributors especially need encouragement. You can reject PRs while being gracious.
Should I use CLA (Contributor License Agreement)?
Only if legally required. CLAs add friction and deter contributions. Most projects use DCO (Developer Certificate of Origin) instead—a simple sign-off in commits. Large corporate-backed projects may require CLAs for legal reasons.
How do I handle contributors who disappear mid-PR?
Wait 2 weeks, then comment asking for status. After 4 weeks, close or adopt. "Hi! Just checking in—are you still working on this? If not, no worries—we can close this or someone else can pick it up." Be understanding—life happens. Make it easy to hand off work.
Use this template to create contribution guides that grow your contributor community. For faster documentation, try River's open source documentation tools.