If you maintain an open source project and want to attract contributors to it but don’t know where to start, the OSPO network is here to help! This guide will walk you through setting up the essential documentation and infrastructure a contributor-friendly project needs.
Every OSS project seeking contributors needs to have the following files in the root directory of the project’s repo.
README¶
The first page a potential new user will see when investigating your project will be its README.md file, which is usually written in Markdown.
Your README should definitely contain:
The name of your project
An overview of the problem your project solves
Instructions for how to set up and use the project
Links to your project’s:
Community discussion space, if you have one (like Discord, GitHub Discussions, or forum)
Contact info: maybe a name and email address, or even just a brief note to communicate by opening an issue (whatever you prefer!)
Citation info, if applicable
Acknowledgements, if applicable
And if you have a bit more time, you could add:
A brief discussion of your project’s non-goals, which will:
Save you and your potential contributing users time by avoiding creating pull requests that won’t be accepted
Help all potential users (contributing or not!) understand your project better!
Screenshots or GIFs of your project
Code examples
Contributing guidelines¶
Users considering contributing to your project will look for its CONTRIBUTING.md file to find guidelines on:
How to set up a development environment
How to run tests
Creating issues
How to identify issues they might work on
Communication
Code and style conventions
Commit conventions
Creating pull requests
You might also like to set up templates for contributors to use when creating issues and pull requests:
Code of Conduct¶
All OSS projects need a Code of Conduct (COC) to establish expectations of behavior, and there’s no shortage of templates to use for ideas. The Contributor Covenant is a great place to start!
Open source license¶
A project can’t be open source without a license, and the Office of the President has created a guide to choosing a license that makes sense for your project and meets UC requirements.