Note to reader: Time stamps embedded in the text below in [ ] are there to help you navigate to the related section of the full interview video included in this blog.
Open source governance best practices
Open Source projects start because developers with expertise want to create new software solutions, but writing the code is only one part of the solution. When it comes to attracting a larger team of coders and benefiting from the open source community, governance becomes important.
Fortunately, after 20 years of open source, the industry has developed a number of proven governance models, free-to-use licenses and even a values statement template that make it easy to set up a governance model for any project.
In a recent interview with Josh Berkus of the Open Source Initiative and Cloud Native Computing Foundation (CNCF), we took a deep dive into the resources available to projects and what Josh has learned from his 25 years in the industry, working at organizations including Linux, PostgreSQL, Perl, OpenOffice, Django, MySQL, CouchDB, Docker, and Kubernetes.
Govern like the industry leaders… NOT!
When projects start out, they can get a boost on governance by using an appropriate template for initial governance. When you’re a small project, choose a governance model that matches your size rather than trying to emulate a project that is already well-developed and has a larger number of participants.
It’s easy enough to find good examples of governance models for any type of open source project, because they are publicly available on Github or Gitlab, and resources such as the Minimum Viable Governance project and CNCF provide free-to-use templates and formats that integrate the most common elements of governance for open source projects.
Josh pointed out four of the most common mistakes to avoid in creating open source governance:
- Don’t copy the governance of large projects when you’re starting out.
- Don’t try to write your own license.
- Don’t neglect to have clear documentation of all procedures.
- Don’t have “coffee room” governance: follow the procedures in all cases.
To ensure you don’t make any of these mistakes, I’ve gone into detail on the best practices for governance that we discussed, and I’ve listed some of the resources that Josh cited for getting started.
Why governance is important
First of all, what is governance? For most open source projects, the initial governance model focuses on how the pull requests are accepted to the repository. Anyone who joins the project wants to know when and how their code contributions are accepted. One of the most frequent sources of misunderstanding is when a coder gets positive feedback on their code, but it isn’t integrated into the source because it’s still going through the approval process. Even with a team of small people, formal governance structures eliminate uncertainty [2:56].
Right-size your governance
Often, founding teams have visions of how huge their project will grow, so they want to choose a governance model that will “scale” as the project expands. That’s a mistake, Josh says. The initial governance documents should be precise in naming the people who are actually doing the approvals process. If you choose a document from a large project such as Kubernetes, you won’t have enough people to fill all the positions mentioned in the governance model. As the project grows, you can upgrade the governance structure, but it’s best start with something simple that everyone can understand.
An easy way to go is to start with the Simple Maintainer Governance templates from the CNCF [4:50]. The governance-maintainer files include a template you can fill in that basically just indicates the roles in the project and who is filling each roles. As Josh points out, most projects already have these procedures in places. They just haven’t bothered to document what they are doing, which ends up wasting time and causing misunderstandings among the project participants.
One of the benefits of having a clear governance model is that it welcomes new people into the team. When coders have clarity about how their participation will be assessed and accepted into the repo, it becomes obvious that the project is open to outside contributors beyond the core team.
What is minimal viable governance?
Josh goes into some of the common elements that are necessary for a successful governance policy [9:45]. Choosing a common public license is a first step, and the other three elements include specifying leaders and documenting the communications and approvals processes. Keeping all of the documentation public, complete, and updated will help avoid misunderstandings. Of course, as we discuss, you need to actually execute the governance to build trust that the team is trustworthy.
Turnover of project participants
With older projects such as Kubernetes, one of the problems that arises is that developers move on to new projects. Entire companies can go out of business [14:20], leaving a gap in the development team which needs to be handled. Josh goes into how different organizations have sub-groups, referred to as Special Interest Groups (SIGs), committees, or Technical Advisory Groups (TAG). Each sub-group has specific areas of responsibility that are stipulated by the governance model.
Comparing open source to local governance
One of the issues that came up repeatedly is that developers want to understand the procedure for accepting their code contributions. When someone writes code they are anxious to find out when it will get integrated (pulled) into the core code. In Josh’s experience, the types of complaints in these projects are similar to local governance participation [20:45]. Volunteers accept decisions, but only if they are done in accordance to the governance documents. Even when the team makes a good decision, if it wasn’t made according to the procedure, developers feel trust was violated and will often leave the project. In other words, it’s not enough to have governance documents, but the team needs to actually implement the governance procedure. Josh works with a number of small open source projects in making the move from a one-company core team to opening up to a wider contributor base and gives us some tips on “Minimum Viable Governance” and implementation shortcuts.
Get lazy: reuse existing models
I always say that coders are lazy: we reuse anything we can rather than writing new code [25:50]. The same goes for governance and licensing. One of the worst decisions you can make is to write your own license agreement. The Open Source Initiative has approved dozens of licenses, and the most popular licenses listed here are usually good enough for most projects. Blockchain projects may want to consider the more recent Cryptographic Autonomy License which prohibits the code developers from having any control of the private keys of their users.
Similarly, governance models can be downloaded from a number of sources such as the Minimum Viable Governance project and CNCF. There’s even a template for standard values. While I don’t recommend copying other people’s values word-for-word, having a basic framework of shared values definitely gives you a boost over having to re-invent the entire thing.
Document and follow through
Getting the documentation up on the repository makes your life easier, because you can easily resolve any misunderstandings with coders who want to make submissions. Usually, the procedure is fairly straightforward. Some projects require only one approval from a core member to integrate a pull request, but many have two or more approvals requirements.
The approval process often requires more than just posting a pull request: coders need to reach out to the approvers. It’s not enough to know that the code is good when approving a pull request. You also want to check out the developer and make sure that they will be around to maintain the code as the project progresses. For that reason, coders may need to reach out personally to push through the approvals.
For most pull requests, the process goes pretty quickly, but for large code bases, things can take longer. Josh mentioned that on Kubernetes, there are multiple committees for different areas of code. Different organizations use different names for these groups: Special Interest Groups (SIG), Technical Advisory Groups (TAG) or simply sub-groups [17:50]. When a pull request touches on different modules, the approval may require approvals from each group, which can extend the process [16:53]. But again, as long as this process is well documented, participants can at least follow up and understand why it’s taking time for their pull request to get approval.
While we didn’t go deeply into the area of implementation, Josh indicated several times that it can be easier to publish the documents than to actually implement all the policies for every pull request.
Maintain trust
If a team is close-knit or has been working together for a while, it’s easy enough to integrate the code without going through the formal procedure–but that quickly erodes trust in the governance of your project. To encourage contributors to come and stay, you’ll need to make sure that you maintain the discipline of going through the appropriate approvals process every single time, even for your OG core developers.
We’d love to hear what you think. Ask a question or leave a comment below.
And stay connected with Cisco DevNet on social!
LinkedIn | Twitter @CiscoDevNet | Facebook | Developer Video Channel
CONNECT WITH US