Contributing Guide Generator
Generate CONTRIBUTING.md files for your open source projects.
Why Contributing Guidelines Matter
A well-written CONTRIBUTING.md file makes it easier for people to contribute to your project. It sets expectations, reduces friction, and helps maintain quality and consistency.
Benefits of Contributing Guidelines
For Contributors
- Clear process for getting started
- Understanding project standards
- Knowing what to expect
- Feeling welcomed and valued
For Maintainers
- Fewer low-quality contributions
- Less time explaining processes
- Consistent code quality
- More time for meaningful work
Essential Sections
Establishes behavioral expectations and creates a welcoming environment. Should cover:
- Expected behavior (be respectful, constructive, inclusive)
- Unacceptable behavior (harassment, discrimination, trolling)
- Enforcement and reporting procedures
- Consequences for violations
Tip: Consider adopting the Contributor Covenant, a widely-used code of conduct.
Help new contributors set up their development environment:
- Fork and clone instructions
- Development environment setup
- How to run tests
- How to build the project
- Links to additional documentation
Guide contributors on submitting quality bug reports:
- Where to report (GitHub Issues, etc.)
- Search existing issues first
- Information to include (steps to reproduce, expected/actual behavior, environment)
- Screenshots and error messages
- Link to bug report template
Set expectations for feature requests:
- Project vision and scope
- What makes a good feature request
- Discussion process
- Timeline expectations
- When features might be rejected
Clear steps for submitting contributions:
- Branch naming conventions
- Commit message format
- Testing requirements
- Documentation updates
- Review process and timeline
- What happens after approval
Define code quality expectations:
- Code style guide (or link to it)
- Naming conventions
- Comment/documentation requirements
- Testing standards
- Performance considerations
- Linter/formatter configurations
Pull Request Checklist Example
Provide a clear checklist for contributors:
## Pull Request Checklist
Before submitting your PR, please review and check the following:
- [ ] Code follows the project's style guidelines
- [ ] Self-review performed
- [ ] Comments added for complex/unclear code
- [ ] Documentation updated (if needed)
- [ ] No new warnings generated
- [ ] Tests added for new features
- [ ] All tests pass locally
- [ ] Dependent changes merged and published
- [ ] Changelog updated (if applicable)Commit Message Guidelines
Many projects follow conventional commit formats:
## Commit Message Format
type(scope): subject
body (optional)
footer (optional)
### Types:
- feat: New feature
- fix: Bug fix
- docs: Documentation changes
- style: Formatting, missing semicolons, etc.
- refactor: Code restructuring
- test: Adding tests
- chore: Maintenance tasks
### Example:
feat(auth): add OAuth2 login support
Implement OAuth2 authentication flow for Google and GitHub.
Users can now sign in using their existing accounts.
Closes #123Best Practices
- Be welcoming: Use inclusive language and assume good intentions
- Be clear: Write step-by-step instructions, not assumptions
- Be realistic: Set honest expectations about response times
- Be specific: Provide examples of good and bad contributions
- Be concise: Keep it as short as possible while being complete
- Provide templates: Link to issue and PR templates
- Link to resources: Point to style guides, documentation, etc.
Remember: Your CONTRIBUTING.md is often the first interaction new contributors have with your project community. Make it count!
Quick Tips
- Place in repository root
- Link from README
- Keep it up to date
- Use clear examples
- Thank contributors
- Make it easy to find
- Be welcoming and friendly
Great Examples
Learn from these projects:
Related Files
Complement CONTRIBUTING.md with:
- CODE_OF_CONDUCT.md
- .github/ISSUE_TEMPLATE/
- .github/PULL_REQUEST_TEMPLATE.md
- SECURITY.md
- GOVERNANCE.md