Guide to Open Source - Part 2
In this series of blog posts, I explain Open Source Software. I’m calling it the Guide to Open Source. This is Part 2 of this series. Here is the link to Part 1 if you haven’t read it. Blog post also available in Linkedin here
How to launch an Open Source Project
The following section describes the simple steps that you should follow to open source your project, it doesn’t matter how big or complex, it’s a great opportunity to share your work, receive feedback and attract participation.
While open source is focused on software, you can open source anything, an idea, a work in progress or after years of being closed source. This guide is focused on Open Source Software (OSS).
No matter at what stage you decide to open source your project, every project should include the following documentation and should be made available to the public.
Open source license
README
Contribution guidelines
Code of conduct
The most common space to publish your code is GitHub, but there are many other options including directly from your website.
Once you publish your code, you are no longer the owner, instead, you are a maintainer. As a maintainer of your project, these files will help you communicate expectations, manage contributions, and protect everyone’s legal rights (including your own). They significantly increase your chances of having a positive experience.
If your project is on GitHub, putting these files in your root directory with the recommended file names will help GitHub recognize and automatically surface them to your readers.
Choosing an Open Source License
Open source licenses allow the software to be freely used, modified, and shared. There are differences between license types. The most common open source licenses are:
There are many more types of licenses for developers, companies and legal teams to choose from, here’s a comprehensive list of GNU Project licenses and Open Source Initiative license types.
These questions can help you narrow down the best license type for your project:
How much license reciprocity is required with respect to the software, modifications, and any derivatives someone develops?
What legal jurisdiction covers the license?
This site provides general guidance to choose your open source license choosealicense.com
You should always include a license file in your code. If you don’t want any restrictions just make it open with free distribution with Apache or MIT licenses, both are the most used in OSS.
Due to the way copyright works, if you don’t have a license file nobody is lawfully able to use the code and even though it’s available online it can’t be considered open source. On the other hand, if you are using code without a license file you are not using open source software, the owner can potentially request retributions or sue you.
Write a README file
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, and what are the goals of the project. If you don’t want to accept contributions, or your project is not yet ready for production, write this information in your README file.
Contribution guidelines
You can define your contribution guidelines file with information about coding style, language, formatting, bug/ticket numbers, release timing, and more.
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. For GitHub 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 send pull request or postings on mailing lists
Projects with a large number of contributors add public JIRA projects to submit feature requirements and report bugs. Note that many OSS that started from private/close code from companies use JIRA, ServiceNow or similar software to receive feedback for their roadmaps as well as bugs tracking.
Code of Conduct
It’s very important to define rules of engagement, a code of conduct empowers you to facilitate healthy, constructive community behavior. Being proactive reduces the likelihood that you, or others, will become fatigued with your project, and it helps you act when someone does something you don’t agree with.
A code of conduct describes the following:
Where the code of conduct takes effect
Whom the code of conduct applies to (community members and maintainers)
What happens if someone violates the code of conduct
How someone can report violations
As a reference, you can check the Contributor Covenant, a code of conduct used by over 40,000 open source projects, including Kubernetes, Rails, and Swift. The Django Code of Conduct and the Citizen Code of Conduct are also good code of conduct examples.
Place a CODE_OF_CONDUCT file in your project’s root directory, and make it visible to your community by linking it from your CONTRIBUTING and README files.
In the next blog post, I’m going to cover the different types of roles within an open source project, how to publish, and what not to publish. After those introductory concepts, I’m going to describe how a company can become an open source company.