In a previous article, we helped you submit your first contribution. You now want to launch your own open source project but you don't know what to do before letting everyone view your code ? No worries, in this article we will give you all the pre-requisites you need to launch your project.
Pre-requisites
If you want your project to have contributions you need to write a minimum of documentation. There are four files that are essential:
- Readme
- License
- Contributing guide
- Code of conduct
We will describe each one and provide you guides to help you write them.
README
The first one is well known and you probably already have one, but let's talk a bit about README.md.
Mike McQuaid theorized about the open source contributor funnel and how to get contributors on your open source projects. You need to provide information for every type of visitors (users, contributors, maintainers) in your readme.
Your project description and first paragraph of your readme should be a simple summary of your project which hits all the important keywords that people search for.
-- Andrey Petrov
First of all, nobody is in your head. You should explain the goal of your project. It doesn't have to be an essay, a single sentence is good enough like in Conference Hall’s readme.
Conference Hall is an opened SaaS platform to manage call for papers and speakers submissions for your conferences and meetups. Speaker writes a talk once and can submit it to every events of the platform.
This section is the first thing a newcomer will read on your project, you need to catch their attention.
Another important part to document in your readme is how to install and use your project. It is essential for users to be able to easily test it. Gatsby does a good job explaining how to have a website running in 5 minutes with their cli.
Last but not least, you should provide instructions for future contributors. A section that links to your contributing guide is enough most of the time.
A template is available on makeareadme.com. It contains all the sections we talked about. You can find more information about how to write a good readme on this website. You can also use tools to generate your readme like readme-md-generator. It fills it with information extracted from git configuration or your package.json file if your project is made with JavaScript. You can find readme generators for various languages on GitHub.
License
The LICENSE file is what makes open source possible. It protects both users and contributors by giving them rights to use, copy, modify and contribute to your project. This file is mandatory, you should consider not contributing to projects that don't provide a license.
OSI is an organism that has been promoting open source software and communities for over 20 years. They have a process to review licenses. The OSI-approved licenses are the most popular ones like MIT or Apache 2.0. You can find a good comparison between licenses on choosealicense.com.
Contributing guide
A CONTRIBUTING.md file, in your open source repository or site, provides potential project contributors with a short guide to how they can help with your project or study group. It is convention to capitalize the word "contributing" as the file title, and to save it as a resource in markdown (hence the extension .md).
-- Mozilla Science Lab
Earlier we talked about "The open source contributor funnel" in our readme, we provided documentation to help users installing and using your project, we will now focus on contributors. The contributing guide is designed to give instructions to everybody that wants to participate to your project.
Most of the time contributions are made by users because they encounter an issue using your project. It's nice to have instructions on how to report a bug or suggest a new feature.
If you want code contributors you need to provide all the details on how to set up the project's development environment and how to submit a contribution. Mocha's contributing guide is a good example of step by step instructions to get your contribution merged.
The contributing guide is also the right place to describe coding styles. You can enforce good practices such as testing or conventions like in the Immutadot's contributing guide.
If your project is on GitHub, this file will be automatically linked when a contributor opens an issue or creates a pull request.
Code of conduct
Having a CODE_OF_CONDUCT.md in your public repository lets potential contributors know in advance how they can expect to be treated by the community and maintainers.
-- Michael Jolley
The code of conduct of your project is a document that protects every participant. It helps creating a welcoming community.
A good addition to your code of conduct is an explanation about how you plan to enforce it. It's important to show that you take it seriously so everybody knows what action will be taken in case of a code of conduct violation.
You should also clarify the way to report a violation, such as through an email.
The most famous code of conduct is Contributor Covenant. It is used by thousands of open source projects. If your project is on GitHub you can directly add Contributor Covenant or Citizen Code of Conduct through your repository interface. You need to go to Insights > Community > Code of conduct, then by clicking on the Add button and choosing a code of conduct, it will create a commit for you.
Your project is now ready to be open sourced. You can start promoting it and getting your first contributions!
If you want further news about our projects or future articles consider following our twitter @ZenikaOSS!
Top comments (10)
Nice post, this is definitely mandatory for anyone to be able to contribute to your open source project.
I would also add the following steps :
Thank you Maxime! Sure I planned to write an article about how to maintain an open source project with all these topics in it. This one was more beginner oriented. In my opinion it was two separate subjects, what do you think of it?
Step-by-step is a good idea 😉
For someone who mark react as one of his/her skill you seem to have missed what happened 3 days ago about code of conduct. The politically correct is a rhetoric only used by people who doesn't want to question their conduct and doesn't care about others.
I'm really sad to see people still using that kind of argument and against code of conduct.
Regarding the license, furthermore than adding a LICENSE file to the project I think it's common, correct my if I'm wrong, to add also a last chapter about it in the README
Sure, that's a good point, thank you! You can see this kind of section in this readme template from makeareadme.com.
Cool 👍
Nice post, very well done.
Glad to read you liked it. Thank you!
great