Start Creating

Start Creating/Making your first Open Source project

Generally speaking, you should open source your project when you feel comfortable having others view, and give feedback on, your work.

A big part of making a project open source is documentation. Every project that is in Github or Gitlab should have several vital documents included in the repository:

Open source license – This defines what others can do with your code, and under what licenses they are allowed to add to your project.
README – This both the intro to your project and more in depth technical documentation. This can include how to set up environments to work on your project or dependencies needed for the code to work.
Contributing guidelines – In order to make your project be sustainable, it helps to define how people can contribute. It may lay out what is needed to submit a pull request, or other ways that are not code that might help (like community management) and ways to contact you.
Code of conduct – Like any ecosystem, it is important to lay out the rules for the group that are working on the project. It does not take much for toxicity to change a community and it takes even more work to bring it back to a healthy environment. There are many templates to pull from, but if you have a code of conduct, take it seriously and enforce the rules consistently.

These documents will help you communicate expectations, manage contributions, and protect everyone’s legal rights (including your own).

For projects hosted on GitHub or Gitlab it is common to put these files in your root directory. By using standard naming conventions, GitHub recognize and automatically show them as important documents to others.

Choosing a license

An open source license guarantees that others can use, copy, modify, and contribute back to your project without repercussions. It also protects you from sticky legal situations. You must include a license when you launch an open source project.

Legal work is no fun. The good news is that you can copy and paste an existing license into your repository. It will only take a minute to protect your hard work.

MIT, Apache 2.0, and GPLv3 are the most popular open source licenses, but there are other options to choose from.

When you create a new project on GitHub, you are given the option to select a license. Including an open source license will make your GitHub project open source.

Writing a README

READMEs do more than explain how to use your project. They also explain why your project matters, and what your users can do with it.

In your README, try to answer the following questions:

What does this project do?
Why is this project useful?
How do I get started?
Where can I get more help, if I need it?

You can use your README to answer other questions, like how you handle contributions, what the goals of the project are, and information about licenses and attribution. If you don’t want to accept contributions, or your project is not yet ready for production, write this information down.

Sometimes, people avoid writing a README because they feel like the project is unfinished, or they don’t want contributions. These are all very good reasons to write one.

For more inspiration, try using @dguo’s “Make a README” guide or @PurpleBooth’s README template to write a complete README.

When you include a README file in the root directory, GitHub will automatically display it on the repository homepage.

Writing your contributing guidelines

A CONTRIBUTING file tells your audience how to participate in your project. For example, you might include information on:

How to file a bug report (try using issue and pull request templates)
How to suggest a new feature
How to set up your environment and run tests

In addition to technical details, a CONTRIBUTING file is an opportunity to communicate your expectations for contributions, such as:

The types of contributions you’re looking for
Your roadmap or vision for the project
How contributors should (or should not) get in touch with you

Using a warm, friendly tone and offering specific suggestions for contributions (such as writing documentation, or making a website) can go a long way in making newcomers feel welcomed and excited to participate.

For example, Active Admin starts its contributing guide with:

First off, thank you for considering contributing to Active Admin. It’s people like you that make Active Admin such a great tool.

In the earliest stages of your project, your CONTRIBUTING file can be simple. You should always explain how to report bugs or file issues, and any technical requirements (like tests) to make a contribution.

Over time, you might add other frequently asked questions to your CONTRIBUTING file. Writing down this information means fewer people will ask you the same questions over and over again.

For more help with writing your CONTRIBUTING file, check out @nayafia’s contributing guide template or @mozilla’s “How to Build a CONTRIBUTING.md”.

Link to your CONTRIBUTING file from your README, so more people see it. If you place the CONTRIBUTING file in your project’s repository, GitHub will automatically link to your file when a contributor creates an issue or opens a pull request.