A guide to the logistics of becoming an open source project
On April 1, we announced the release of the StackRox Community Platform. This is the result of a great deal of work by our team to transition StackRox’s popular proprietary security platform into an open source one.
Transitioning a project from private to public development means more than just changing the visibility of the GitHub repositories. It is essential to have a transition plan, especially if the goal is to build a thriving community where users can grow and leverage the platform. To have the best chance of success, the project’s goals and the community’s goals should be as aligned as possible.
For the StackRox team, one of our top goals was to set the entry barrier as low as possible for contributors and community users. I’ve personally found this to be a significant challenge. It is one thing to tailor your environment to engineers, hoping to provide a thorough and guided onboarding experience. Creating a forum for a greater community of developers, operational and security folks poses an entirely different challenge.
Part I: Your Product and Your Engineering Team
What Do We Open Source?
If you look at the StackRox GitHub organization, you will find a multitude of repositories with the platform comprising many different components and features that could be kept private. However, we chose to be thorough and take the extra time. We decided to open the complete platform and all its dependencies, including our out-of the box policy ruleset that we ship on new installations and pre-built Docker images and Helm charts, to make the open source deployment as easy as possible.
What License Do We Use?
When opening your source code, the first task should be to select a license that fits your use case. In most cases, it is advisable to include your legal department in this discussion, and GitHub has many great resources to help you with this process. For StackRox, we oriented ourselves on similar Red Hat and popular open source projects and picked Apache 2.0 where possible.
How Can People Access It?
After you’ve decided on what parts you open up and how you will open them, the next question is: How will you make this available?
Besides the source code itself, for StackRox, there are also Docker images, as mentioned. That means we also open the CI process to the public. For that to happen, I highly recommend you review your CI process. Assume that any insecure configuration will be used against you. Review common patterns for internal CI processes like credentials, service accounts, deployment keys or storage access.
Also, it should be abundantly clear who can trigger CI runs, as your CI credits/resources are usually quite limited, and CI integrations have been known to run cryptominers or other harmful software.
How Do We Manage It?
StackRox is built as an upstream public build, whereas Red Hat Advanced Cluster Security (RHACS) is built on an internal Red Hat build system. Tending to two different build pipelines naturally brings some overhead, as the open source and commercial flavors of this project each have different needs.
If all goes well and your CI succeeds, you most likely end up with some artifact — a release binary, tgz file or Docker image.
How Do We Distribute It?
Making these artifacts publicly available to, again, lower the barrier of entry is essential.
For StackRox, we decided to push built images to a public organization at Quay, https://quay.io/stackrox-io. Alternatively, you can use GitHub’s release feature or other public distribution channels, depending on your release artifact type, such as NPM, PyPI, Crates. After distribution, the next step would be users downloading these artifacts and running your product. This brings us to the next important question.
How Do We Document It?
The project documentation is your public representation of your project, inviting users and contributors alike. Potential users will often consult your documentation first to gauge whether your project fits their use case and understand how to use it most efficiently. Documentation is ideally written to convey information to the community while minimizing user confusion and clarifying issues in your GitHub repository.
Remember that documentation for operators and developers are two very different things. For example:
- Operators are interested in the deployment, configuration, platform maintenance, data preservation, updates and disaster recovery.
- Developers are interested in setting up a development environment ( IDE, local deployment, debug builds, etc.) and getting access to detailed API descriptions.
Both target audiences profit heavily from “Getting Started” guides, be it how to get your first deployment up and running (operators), or how you accomplish everyday extension tasks in the codebase (developers).
Because StackRox is upstream of RHACS, we decided to focus our documentation efforts on developers, as quite a lot of user-tailored documentation is available at https://docs.openshift.com/acs/. Open source-specific user documentation with StackRox branding is a project we’re planning right now.
Our developer-tailored documentation is being expanded in the main projects’ README and stackrox/dev-docs. The latter is a collection of Markdown guides that initially started as private Confluence articles. This collection keeps growing, especially as we get more feedback from contributors on which guides they would like to see. It is also a continued effort to migrate additional guides and how-tos that might have been missed in the first migration, or that might not have been published because they contain private information.
How Do We Manage Privacy?
Speaking of private information: Due to the nature of git, the complete history of your project will be public, starting with the first commit to the repository you publish. This also applies to any issues, discussions and pull requests that your project collected over time. While this is a non-issue for internal development, this can pose quite a problem when going public.
It is heavily advised that you review all your issues and comments — on GitHub or other git repository — and scrape the project’s git history for any information or references not intended for public use. This information does not need to be public to be considered open sourced, but it does add context for future users, so you might want to keep as much of it intact as possible.
A quick and easy way is to start with a new project on GitHub and do away with your git history. This poses multiple problems, however.
Your engineering team loses the history of their work, problem-solving and discussions, which are valuable resources. Furthermore, this step has to be planned well, and the engineering team must be in the know — if one person pushes their old git history to your new project, the complete history will be accessible again.
How Do We Handle CVEs?
Speaking of visibility: If you handle CVE/embargoed work, you will need a workflow in place. As your repository is public, you cannot simply use a public feature branch for this kind of work. For example, GitHub provides the option of temporary private forks to resolve security issues.
How Do We Take Care of Our People?
Last but not least: As already mentioned, in all of these tasks, you should take care to keep your engineering team involved and in the know at all times.
The Red Hat Advanced Cluster Security (RHACS) engineering team works in a design-document-driven process, where all major changes are discussed between the whole engineering team through shared documents and discussions, written (document comments) and spoken (review meetings).
In the months leading to our announcement, we conducted many discussions and tried to find solutions, workflows and approaches that the team was happy with.
As the engineering team will still be the main driver for the project, they should know what changes in their daily work once you go open.
Additionally, this is an excellent opportunity for initial external OSS contributions. If you maintain private forks with product-specific patches, this is the chance to shine by offering these changes to the original upstream projects.
For our engineers, little changed. They still work primarily in the upstream repositories, with the main difference that all pull requests and their discussions are now publicly visible. This change means that teams need to be mindful of how they communicate, even internally, as all comments can be read by external people who might lack the context or shared humor your team has.
Part II: Community, Collaboration, Context
How Do We Enable Healthy Discussion?
As your audience grows, it is vital that you define clear rules to create a safe environment for everyone to participate. A common way of doing this is to define a Code of Conduct (CoC), which sets some basic guidelines on what kind of community interaction will not be tolerated. We decided to stick to well-established frameworks and based our CoC on the Contributor Covenant.
How Do We Help Keep the Discussion Healthy?
The best CoC definition doesn’t help if there is no one there to enforce it. This meant we needed to find volunteers for a CoC Committee and train them accordingly. The committee members should be publicly available and open for communication so they can be approached in case of any problems.
We did this by publishing the CoC and the committee members on our community website, https://www.stackrox.io/code-conduct/.
Where Can We Communicate with the Community?
At this point, you should be aware of the goal of your open source go-live and the expected target audience. Answers to these questions shape how you interact with your community. Use all channels you have to reach out, but decide on one discussion medium out of the plethora available today, such as Slack, Discord, mailing list, forums or Matrix.
The StackRox community currently lives on the CNCF Slack workspace in the channel #stackrox.
How Do We Accept Contributions?
Be clear and concise in what you accept from contributors. Is it only feedback in discussions? Do you accept issues or pull requests on GitHub? If so, it is recommended to provide guidelines in the form of a CONTRIBUTING.md document or Issue / PR templates to fill out.
If you decide to accept these, it also helps to give people a rough idea of your reaction times. Also, be sure to have processes in place to decide who keeps an eye on new items.
For example, we communicate that we aim to triage new issues and PRs within a week, with more detailed discussions and decisions communicated in our monthly meetings.
How Will We Meet with the Community?
Regular public meetings lower the bar for participation and allow for issues to be raised efficiently. Any interested contributors can quickly stop by and get in touch with your project.
Currently, we run our StackRox Community meeting on the second Tuesday of each month at 9 am PST / 12 pm EST / 5 pm GMT. You can subscribe to the events by adding the calendar community@stackrox.com to your calendar.
In these meetings, we discuss and show demos of upcoming features, talk about open issues, present guides and how-tos, and have an open forum for Q&A with the community.
Part III: Your Turn
Over the past year and a half we have worked diligently to bring you a complete open source Kubernetes security platform. The next step for us is to help harden as many container workloads as possible. To accomplish this goal we need feedback from users. We would love to see you in our Slack channel, starring the GitHub repository and becoming our monthly “RoxStar.”
If you have any questions or would like to contribute to StackRox, stop by in the CNCF Slack or join the next community meeting!