The development of public code requires various forms of governance. Codebase stewardship includes helping communities develop the governance models that best suit their specific situations. We recognize that governance is not “one size fits all”, but rather something that needs to be adjusted to the culture, maturity, composition, and size of a community.
The Foundation for Public Code does not directly govern codebases. Instead, we offer support and advise on codebase governance, and help communities execute governance.
What codebase governance is
Codebase governance is strictly limited to the codebase. The governance of the codebase should strive to be as simple, transparent and welcoming as possible. This is to help the codebase scale, and allow different types of parties; public associations, large and small municipalities, and different companies to get involved. The current draft ‘governance file’ contains a proposal, including a technical steering team and product steering team.
Codebase governance does not imply governance of implementations
Governance of implementations is whatever contextual arrangement is made to enable a local implementation. This can include contracting of marketing parties, collective procurements, or service agreements between municipal departments. For example, this could include a joint procurement by several municipalities, coordinated by an association of municipalities, for a consortium of market parties (including development, maintenance and hosting parties).
Governance of implementations can vary strongly, ranging from one municipality who does everything in house, to municipalities who interact with a single market party for all their needs and questions.
Below is a visual representation summarizing the information above.
Determining a community’s governance needs
Several basic questions need to be answered regardless of the methods used to determine these needs:
- How do you want to make decisions, large and small, around the codebase and the community?
- Can certain issues only be decided by certain community members?
- Can others be distributed and/or delegated to the wider community or specialists within the community?
- Who decides which issues are reserved or delegated, and how can community members participate in the decision making process?
- Do you want to use a letter of intent to show the commitment of an organization joining the community?
Designing a governance model
After the community’s governance needs have been established, a suitable governance model can be designed. This governance template can be used as inspiration.
The following sections are typically included when designing a governance model:
- Principles
- Maintainership (teams, members and meetings)
- Changes in codebase governance
- Decision-making process
- Conflict resolution
- Intellectual property
- Code of conduct
The governance model is best documented in a GOVERNANCE file that is placed in the root catalog of the codebase repository and linked to from the README file.
The process of establishing governance should not be a blocker for working in the open. It is better to start working in the open, and then work on establishing governance. This is particularly true if the beginning of a codebase involves only one contributing organization. That being said, clear and established governance is essential for effective collaboration, so the closer the codebase is to having additional contributors, the more urgent it becomes to establish governance.
Standard compliance
The Standard for Public Code mentions several criteria related to governance.
Welcome contributions
This criterion has several requirements that are related to the governance of a codebase. Firstly, it makes clear that a lot of things need to be publicly accessible and that things need to be openly documented. It then touches upon on how people can interact and what expectations they can have of the codebase. Lastly, it states that the governance itself should be documented in a GOVERNANCE file.
Require review of contributions
This is the second criterion relevant for codebase governance. It mandates that contributions need to be approved by other parties in the community and specifies how this could be done.
Anti-patterns
Some common anti-patterns that we have noticed are:
- The governance model is set up to require reviewer(s) from other organization(s).
- If one organization makes 90% of the pull requests, the other organizations may not be able to keep up with that pace. If the model is too rigid, timely merging might become a problem.
- If a majority (or all) of the reviewers are part of a single organization that doesn’t dedicate time to reviewing code contributions from other organizations, the backlog of pull requests to review will grow. If the model is too rigid, timely merging might become a problem.
- A model requiring perfect consensus or even unanimous votes might get caught in decision paralysis if the voting members usually have different opinions.
Tools to support governance
These are some tools we’ve developed to make codebase governance easier:
- The governance game and the governance exercise are useful tools to employ early in the process. It helps people reflect on what governance means for a codebase, the complexity around it, and suggests things worth considering during set up. The game is also useful as a tool for visualizing how a current governance model is set up or could be changed in a customized governance workshop.
- Technical roadmap template.
- Template for a letter of intent of joining a codebase.
Further reading
- Open Governance - a collection of governance models of open source projects (no public code examples there yet).
- Some easy tasks related to governance are listed in Product assets for early incubation.