DEV Community

Cover image for Preparing your project being open sourced
🦁 Yvonnick FRIN for Zenika

Posted on • Updated on • Originally published at oss.zenika.com

Preparing your project being open sourced

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)

Collapse
 
notsag profile image
Maxime Gaston

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 :

  • use a proper logging system (not just print/echo)
  • have at least basic local tests and static code analysis to ensure a minimal level of quality
  • have issue templates to be ready to receive feature ideas or bug reports
  • have a basic documentation (or at least docstrings in the code and a plan to generate documentation)
  • setup continuous integration (using Travis, Azure pipelines, Actions...)
Collapse
 
yvonnickfrin profile image
🦁 Yvonnick FRIN • Edited

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?

Collapse
 
notsag profile image
Maxime Gaston

Step-by-step is a good idea 😉

Collapse
 
louckousse profile image
louckousse

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.

Collapse
 
daviddalbusco profile image
David Dal Busco

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

Collapse
 
yvonnickfrin profile image
🦁 Yvonnick FRIN • Edited

Sure, that's a good point, thank you! You can see this kind of section in this readme template from makeareadme.com.

Collapse
 
daviddalbusco profile image
David Dal Busco

Cool 👍

Collapse
 
ben profile image
Ben Halpern

Nice post, very well done.

Collapse
 
yvonnickfrin profile image
🦁 Yvonnick FRIN

Glad to read you liked it. Thank you!

Collapse
 
elvinaqa profile image
Elvin Aghammadzada

great