By Nisha Kumar, open source engineer, VMware
At minimum, what should go into an open source project to give it the best chance of success? We’ve been asking ourselves this question lately at VMware’s Open Source Technology Center (OSTC). In this post, I’ll share some pointers we’ve come up with on how to get your new or existing internal project ready for open source.
First, though, I want to note an aspect of open source projects that folks coming from the proprietary space often miss: when you open source a project, you are sharing your thought process, design decisions and implementation with the world. So if you have any proprietary secrets in your source code, data or documentation, you should either remove them from your project before open sourcing it or reconsider whether open source is right for you. Having said that, there are many benefits to open sourcing your project. Once you share your work, your users will be able to view, download and modify it to fit their use cases. These crowd-sourced modifications are exactly what you want to leverage for your project, making it more robust and secure.
In order to make your open source project successful, you should focus on making it easy for your users to submit modifications to your project’s content and infrastructure. Below are some general rules of engagement to consider:
- You want to pick a minimum of two maintainers for your project so that it has at least one maintainer available at any time.
- You should decide upon—and keep to—one or more communication channels, based on your preference. The Open Source Technology Center recommends maintaining a Slack channel and a mailing list. But remember, submitting issues is also a common mode of communication, so you need to communicate how issues should be submitted, too.
- A code of conduct is useful for keeping discussions and code review positive. At VMware, we make a point to always follow VMware’s Business Conduct Guidelines and EPIC2 standards when communicating with the public.
- Pick a suitable license for your open source project based on how you would like the public to use your code. Some licenses require a Contributor License Agreement (CLA) or Developer Certificate of Origin (DCA).
- You need a good project description. This helps search engines find your project.
- You may also want to think about documenting coding style and documentation style. This will help you and your contributors focus on improving the project rather than arguing about style.
- Lastly, don’t assume your contributors have the same access as you do. Many, for example, won’t have 24/7 internet or an AWS account.
It’s also worth thinking a little more about how contributor perspectives can differ. Contributors to open source projects come in two flavors:
- A user who wants to solve a problem and thinks your project might help.
- A user who is interested in the space your project occupies (cloud computing, security or programming language) or in contributing to open source in general.
The first kind of user would see that the project does work for her and is inspired to become involved to make it better. If the project does not work for her, she may still want to “scratch the itch” and look for ways to fix it. Either way, your project must make it easy for her to submit her modifications to the project, for both documentation and source code.
Keeping this in mind, you would want in place:
- Documentation that details the problem your project solves and how it goes about trying to solve it.
- Details about the source code and how to navigate it.
- Instructions for how to try it out.
- Instructions for submitting changes to the documentation and source code.
- An issue tracking system if this work is ongoing.
- Documentation for how to navigate your source code.
You can include your documentation in a README.md and instructions on how to contribute in a CONTRIBUTING.md file. CONTRIBUTING.md is also where you may want to document how to get in touch with you. GitHub already comes with issue tracking and a labeling system which you can use to organize communication about your project. Remember to add working source code that works for your simplest case.
The second kind of user is one who probably does not know your project exists and is using the internet to look for a project to contribute to. Although their contributions may be small at first, you want your project to be inviting enough so that they come back.
To help these users, you will want:
- Issue tags, like “help-wanted” or “good first issue,” that help new contributors find issues that are suitable to their experience level.
- A project roadmap indicating what you are currently focused on so that new contributors can find issues that are relevant to them.
- Helper documentation to get new contributors started; e.g., links to blogs, tutorials, online resources or demos.
- A documented service level agreement to set expectations for responsiveness.
For both types of users, keep in mind that the clearer the goals of the project and how it plans on achieving these goals, the more involved contributors will want to be. So being transparent about these aspects is key. When you start getting a good number of pull requests, all of the following will help you add scale:
- Build scripts, unit and functional tests and CI/CD automation to process pull requests faster and more efficiently.
- Feature branches or development branches for managing your priorities.
- Assigning feature owners – preferably from your community.
- Simple workflows to manage any issue backlog.
Lastly, a reminder that if you are considering converting a proprietary product into an open source project, don’t forget to remove references to internal bug tracking systems, links, tools, infrastructure and internal meeting minutes or conversations. If you don’t remove them, not only might you reveal information you shouldn’t, but you can easily break a build. You might also want to remove dependencies on internal or proprietary products, tools and infrastructure, or internally built binaries or modules as well.
Check back into the Open Source Blog for more open source project advice and inspiration, and be sure to follow us on Twitter (@vmwopensource).
