Flatcar Governance Report

# Flatcar Governance Report What follows is a governance review and assessment for the Flatcar project. This review is carried out by members of the Governance Working Group of TAG Contributor Strategy. The review may have been done because of a change in maturity level for the project, at the request of the TOC, or as a request by the project itself. If requested by the project, the review will be provided to the project maintainers. Otherwise, the review will be submitted to the TOC for their follow-up. Projects may ask TAG Contributor Strategy for assistance in resolving any issues uncovered by the review. The TAG is available via our [slack channel](https://cloud-native.slack.com/archives/CT6CWS1JN), [email](https://lists.cncf.io/g/cncf-tag-contributor-strategy), [GitHub](https://github.com/cncf/tag-contributor-strategy), or by joining our weekly meetings (listed on the [CNCF public calendar](https://www.cncf.io/calendar/)). ## Summary and Assessment Flatcar governance is within the guidelines of TAG Contributor Strategy governance mostly. It has a single must-fix issue, which is: - Some repositories in the GitHub organization using a different Code Of Conduct other than the CNCF Code Of Conduct Other than the must-fix issue, there are some recommended actions by the TAG Contributor Strategy and we are hoping to see the Flatcar community take those actions. The governance is updated [very recently](https://github.com/cncf/tag-contributor-strategy/issues/392#issuecomment-1584642543) and there is no public data yet to verify if the written governance is actually used. ### Executing the Assessment  [Danielle Tal](https://github.com/miao0miao) requested the governance review on April 25, 2023 as a part of the process for Flatcar's [acceptance to incubation](https://github.com/cncf/toc/pull/991). The assessment is executed in 2 passes by the TAG Contributor Strategy Governance Working Group and the Flatcar maintainers. The first pass is done by TAG co-chairs, [Dawn Foster](https://github.com/geekygirldawn) and [Josh Berkus](https://github.com/jberkus) based on the [governance document of Flatcar at that time](https://github.com/flatcar/Flatcar/blob/890b6f8be364b27a1c7671897acd5dcaa1c7e824/governance.md). It was reported on the [GitHub issue](https://github.com/cncf/tag-contributor-strategy/issues/392#issuecomment-1536284415) on May 5, 2023. Flatcar maintainers acted quickly based on the results of this pass and [updated](https://github.com/cncf/tag-contributor-strategy/issues/392#issuecomment-1584642543) their governance based on the recommendations. However, their previous governmence was de-facto the same, except some rules were not written. The second pass is executed by the TAG member [Ali Ok](https://github.com/aliok) and [Josh Berkus](https://github.com/jberkus) based on the repository [snapshot at July 7, 2023](https://github.com/flatcar/Flatcar/tree/3e2ba40795aae15404096bb439aa60cf602ca0c4) and this report is prepared. ### Must-Fix Items The following issues have been identified that need to be resolved before Flatcar is being accepted to incubation at the CNCF. - Some repositories, such as [flatcar/nebraska](https://github.com/flatcar/nebraska) and [flatcar/bootengine](https://github.com/flatcar/bootengine) are using a different Code of Conduct other than the CNCF Code of Conduct. ### Areas for Improvement Over the next year, the project should work on the following issues to improve its governance, these are considered non-blocking: * Process of selecting the security response team members should be clarified. * There are some inconsistencies in the voting process for accepting a new maintainer, changing the governance and removing a maintainer. The maintainers need to check the logic of what votes are required for what actions. * Affiliations of the maintainers should be writen in the maintainers file. * Governance document should be easier to find from the website and the contributor guides. * Governance document or the repository it lives in should be linked in the other repositories in the GitHub organization. * Out-of-scope usecases are not described. Additionally, following are the evolutionary suggestions for the project, which should be done when the project grows more: * Contributor Ladder should define more roles. Details of these issues can be found in the [Findings Table](#Governance-Findings-Table), [Suggestions Table](#Governance-Improvements-Suggestions-Table) and the related sections below. ## Review ### Governance Description  Flatcar [started in 2018](https://www.flatcar.org/blog/2018/03/announcing-the-flatcar-linux-project/) and [applied](https://github.com/cncf/toc/pull/991) to CNCF to become an incubating project in 2023, to "support the objective of making it a community-driven project for the benefit of the whole cloud native community". As of July 2023, there are ~53000 active public user instances, which shows the adoption of Flatcar. Flatcar has basic [Maintainer Council governance](https://contribute.cncf.io/maintainers/templates/governance-maintainer/#maintainer-council-governance), which is appropriate for their community. The governance has rules for simple self-selection council of maintainers as project governance. Given the community has 8-10 substantial contributors. this model works for the Flatcar community. Flatcar has a few repositories in the [GitHub organization](https://github.com/flatcar) with no notable divisions that can be considered as projects. These repositories share a pool of maintainers. Governance document targets to embrace openness, fairness, community over product/company, inclusivity and participation. Maintainers are the decision makers in Flatcar; there is no separate council or committe. Decision making requires voting. Voting process is described adequetly and within the TAG Contributor Strategy guidelines except noted in the must-fix items above. When can be voting used, how to start a voting and how to vote are all well defined. As of writing, there are 9 [maintainers](https://github.com/flatcar/Flatcar/blob/3e2ba40795aae15404096bb439aa60cf602ca0c4/MAINTAINERS.md) and 8 of them work for a single vendor, Microsoft. Flatcar has a special security response team. This team's activities are kept private due to security concerns. This team comprises of some of the maintainers that are assigned by the maintainers. The team is documented to be reviewed at least once a year. ### Discoverability #### Governance Location  Flatcar community has pinned the [flatcar/Flatcar](https://github.com/flatcar/Flatcar/tree/3e2ba40795aae15404096bb439aa60cf602ca0c4) repository in [Flatcar GitHub organization](https://github.com/flatcar) and as noted in the [organization README.md](https://github.com/flatcar/.github/blob/31958d506908dec6164b1301982766717b2f306a/profile/README.md), this is the main repository for information on the project and how to participate. This emphasized main repository, is solely used as the community repository with information on governance, contribution guides, adopters and such. Governance documentation is in the mentioned main repository. In the README.md of the main repository, there is text giving a summary of the governance and there is a link to the governance document. The website, https://www.flatcar.org/, doesn't have a direct link to the governance document though. From the website, the only way to find the governance document is to click the GitHub link at the buttom left to navigate to the GitHub organization, then to the main repository and then finally to the governance document. The [docs contributor guide in the website](https://www.flatcar.org/docs/latest/contribute/) doesn't have a link to the governance document. The other contributing guide, [CONTRIBUTING.md](https://github.com/flatcar/Flatcar/blob/3e2ba40795aae15404096bb439aa60cf602ca0c4/CONTRIBUTING.md), doesn't have a link to the governance document too. #### Governance Discovery Completeness  Governance files are named clearly, can be found easily in the repository, and are interlinked to each other. Governance documentation is mentioned in the primary community repository [flatcar/Flatcar/README.md](https://github.com/flatcar/Flatcar/blob/3e2ba40795aae15404096bb439aa60cf602ca0c4/README.md#project-governance). However, there are no links to the governance or the primary community repository from the other repositories. ### Documentation Content  The following table details the governance areas expected for a project. Coverage is indicated by Complete, Partial, and Missing. * Complete - the content of the governance documentation is fully detailed and does not leave any question to the reader. * Partial - the content of the governance documentation is missing some information and would leave the reader with questions or some level of misunderstanding. * Missing - the documentation is absent, wholly undiscoverable, or woefully inadequate in meeting the objectives of that governance content. The reader cannot act on the content that is available. * Unknown - the status of the governance area is unknown and the area cannot be assessed, often because of a limitation on the CNCF side. | Governance Area | Coverage | Finding Notes | |:------------------------------------------|:------------------------:|:--------------| | [Project Purpose](https://github.com/flatcar/Flatcar/blob/3e2ba40795aae15404096bb439aa60cf602ca0c4/README.md#mission-statement) | Complete | Project's mission statement is written in the main repository [README.md](https://github.com/flatcar/Flatcar/blob/3e2ba40795aae15404096bb439aa60cf602ca0c4/README.md#mission-statement) file. However, the use cases that are not in the scope is not listed. | | [Maintainer List](https://github.com/flatcar/Flatcar/blob/3e2ba40795aae15404096bb439aa60cf602ca0c4/MAINTAINERS.md) | Partial | Employer affiliation is missing in the [maintainers list](https://github.com/flatcar/Flatcar/blob/3e2ba40795aae15404096bb439aa60cf602ca0c4/MAINTAINERS.md). | | [Contributor Ladder](https://github.com/flatcar/Flatcar/blob/3e2ba40795aae15404096bb439aa60cf602ca0c4/governance.md#becoming-a-maintainer) | Complete | The ladder embedded in the governance document is only defining the role "maintainer". Ideally, the contributor ladder would have more roles and would look like TAG Contributor Strategy contributor [template](https://github.com/cncf/project-template/blob/main/CONTRIBUTOR_LADDER.md). | | [Maintainer Lifecycle](https://github.com/flatcar/Flatcar/blob/3e2ba40795aae15404096bb439aa60cf602ca0c4/governance.md#removing-a-maintainer) (to include removal) | Complete | Maintainer lifecycle is specified and it includes removal of maintainers because of inactivity, code of conduct violations or voluntary stepping down. | | [Decision-making](https://github.com/flatcar/Flatcar/blob/3e2ba40795aae15404096bb439aa60cf602ca0c4/governance.md#voting) | Complete | It is clear who can make the decisions on behalf of the project and how to do it. However, there are some inconsistencies, which are noted in the other sections of this document. | | [Code and Docs Ownership](https://github.com/flatcar/Flatcar/blob/3e2ba40795aae15404096bb439aa60cf602ca0c4/governance.md#maintainers) | Unknown | Governance states that the maintainers have full access to the repositories they are maintaining. However, a GitHub permissions audit is not possible to be executed at Flatcar at this stage as CNCF cannot audit non-CNCF projects' GitHub permissions and ownership. | | [Security Reporting and response](https://github.com/flatcar/Flatcar/blob/3e2ba40795aae15404096bb439aa60cf602ca0c4/governance.md#security-response-team) | Complete | Security reporting and response is documented well. | | [Communication and Meetings](https://github.com/flatcar/Flatcar/blob/3e2ba40795aae15404096bb439aa60cf602ca0c4/README.md#project-status-and-roadmap---whats-everybody-working-on-right-now-and-in-the-future) | Complete | Information about these are listed in the main README.md file.| #### Sub-projects, plugins, and related The Flatcar project does not have notable subprojects. ### Operation #### Transparency and freshness Transparency for a project is exemplified in the public documentation, record, and communications, allowing observers and contributors to monitor the project's adherence to their stated governance. Freshness indicates governance activities mirror the documented governance for the project, and have been reviewed or updated recently. Flatcar's governance documentation is fresh. As stated in the [Executing the Assesment](#Executing-the-Assessment) section, the governance is updated very recently. Governance activity freshness cannot be assessed as there is no data yet. The previous governance was very similar to the new one, however, there are no public examples of execution of the most of the governance rules, such as voting, having new maintainers and etc. because it was also very [recently created](https://github.com/flatcar/Flatcar/pull/841/) in 2022. #### Governance Drift Governance Drift can occur when the executed and observable governance of a project deviates from the documented governance of the project. As written in the sections above, the governance is updated recently and we cannot talk about any substantial drift at this stage. One issue that can be considered a drift is that the security response team is written to be assigned by the maintainers in the [governance document](https://github.com/flatcar/Flatcar/blob/3e2ba40795aae15404096bb439aa60cf602ca0c4/governance.md#security-response-team), but it is written to be elected in the [SECURITY.md](https://github.com/flatcar/Flatcar/blob/3e2ba40795aae15404096bb439aa60cf602ca0c4/SECURITY.md). Other than the conflicting information, there is no information about how this assignment or election is done. ### Ownership Flatcar uses manually maintained GitHub permissions and teams to manage maintainers and their permissions. The [MAINTINERS.md file](https://github.com/flatcar/Flatcar/blob/3e2ba40795aae15404096bb439aa60cf602ca0c4/MAINTAINERS.md) is not used in any automated setup, but is simply a public information about the maintainers and their roles. The project's ownership evaluation did not leverage Sheriff, the CNCF GitHub permission auditing tool, as it is not ready yet to be used this kind of evaluation. Governance reviewers cannot comment on permissions as they cannot audit permissions. ### Maintainer List(s) The project's [maintainer list](https://github.com/flatcar/Flatcar/blob/3e2ba40795aae15404096bb439aa60cf602ca0c4/MAINTAINERS.md) is current. Individuals on the maintainer list do appear to match the requirements of maintainership in accordance with the project's documented requirements. The project maintainers come primarily from one company (Microsoft), which is normal for a project not yet donated to the CNCF. One listed maintainer does not work for Microsoft, which shows intention to promote leadership from the community. The maintainers list does not specify the affiliation of the maintainers. At some point in the next year, it might be good to adopt a list that is based on the [maintainers file template](https://github.com/cncf/project-template/blob/main/MAINTAINERS.md). ### Evolution Flatcar's Evolution State is "Evolving". Governance evolution is the observable changes and improvements the project makes to its governance over the project's lifespan. It is expected that changes will occur over the project's life and that such changes are iterative, tested, and adjusted. The project's governance evolving with the following major milestones over time: * Flatcar had its first governance document created in [October 2022](https://github.com/flatcar/Flatcar/pull/841/). This was a very simple governance, which didn't cover many project processes. * Flatcar maintainers updated their governance after reaching out to the TAG Contributor Strategy for an initial review part of their acceptance to the CNCF. The governance adopted one of the models recommended by the TAG Contributor strategy. Details of this change can be found in the original [request](https://github.com/cncf/tag-contributor-strategy/issues/392#issuecomment-1584642543). According to project members, this is materially the same as the prior, undocumented, governance. ### Governance Findings Table  | Finding Title | Importance | Description | |:--------------|:----------:|:------------| | Some repositories state a different Code of Conduct | Critical | Some repositories, such as [flatcar/nebraska](https://github.com/flatcar/nebraska) and [flatcar/bootengine](https://github.com/flatcar/bootengine) are using a different Code of Conduct other than the CNCF Code of Conduct. | | Some voting related processes are inconsistent | Medium | The governance states that the approval of a new maintainer requires a [consensus](https://github.com/flatcar/Flatcar/blob/3e2ba40795aae15404096bb439aa60cf602ca0c4/governance.md#becoming-a-maintainer), but [amending](https://github.com/flatcar/Flatcar/blob/3e2ba40795aae15404096bb439aa60cf602ca0c4/governance.md#modifying-this-charter) the governance only requires a 2/3 majority, as does [removing](https://github.com/flatcar/Flatcar/blob/3e2ba40795aae15404096bb439aa60cf602ca0c4/governance.md#removing-a-maintainer) a maintainer. Being able to remove a maintainer easier than approving a new one is inconsistent. | | Process of selecting the security response team members should be clarified. | Medium | While the [governance document](https://github.com/flatcar/Flatcar/blob/3e2ba40795aae15404096bb439aa60cf602ca0c4/governance.md#security-response-team) is saying that the members of this team will be assigned by the maintainers, [security document](https://github.com/flatcar/Flatcar/blob/3e2ba40795aae15404096bb439aa60cf602ca0c4/SECURITY.md) says this team will be elected by the maintainers. There are no details how the team is structured, how maintainers select its members, how the contributor ladder for this team looks like. | | No maintainer affiliation listed in the maintainers list | Low | Employer affiliation is missing in the [maintainers list](https://github.com/flatcar/Flatcar/blob/3e2ba40795aae15404096bb439aa60cf602ca0c4/MAINTAINERS.md). Having this helps the CNCF TOC monitor community-building progess. | | Governance document should be easier to find from the website and the contributor guides. | Low | The governance document is hard to find from the [website](https://www.flatcar.org/), the [contributing guide](https://github.com/flatcar/Flatcar/blob/3e2ba40795aae15404096bb439aa60cf602ca0c4/CONTRIBUTING.md) and the [documentation contributor guide](https://www.flatcar.org/docs/latest/contribute/). One needs to make at least 3-4 clicks to the GitHub organization, then to the main repository, then to the governance document. | | Governance document or the repository it lives in should be linked in the other repositories in the GitHub organization | Low | The project governance should be obvious and one should not need to make an extra effort to remember that there is a governance documented in this project. All the repositories should have a link to the governance document, or the main repository (flatcar/Flatcar). Some examples repositories are [flatcar/scripts](https://github.com/flatcar/scripts) and [flatcar/nebraska](https://github.com/flatcar/nebraska) | | Out-of-scope usecases are not described | Low | In the [mission statement](https://github.com/flatcar/Flatcar/blob/3e2ba40795aae15404096bb439aa60cf602ca0c4/README.md#mission-statement), project's scope is defined but what is not in the scope is not defined. TAG Contributor Strategy recommends defining that and has [a guide](https://contribute.cncf.io/maintainers/governance/charter/#scope) to help. | ### Governance Improvements Suggestions Table This table has evolutionary suggestions for the governance, which we recommend to be done when the project grows more: | Suggestion Title | Description | |:-----------------|:------------| | Contributor Ladder should define more roles. | [Contributor Ladder](https://github.com/flatcar/Flatcar/blob/3e2ba40795aae15404096bb439aa60cf602ca0c4/governance.md#becoming-a-maintainer) embedded in the governance document is only defining the role "maintainer". Ideally, the contributor ladder would have more roles and would look like TAG Contributor Strategy contributor [template](https://github.com/cncf/project-template/blob/main/CONTRIBUTOR_LADDER.md). | ## Template feedback (to be cleaned up by Ali and presented as a separate document): - // How much do we need to mention about the project purpose, state and similar information, which are not in the scrope of this review in a direct way? The problem is the duplication of the text. Assuming the audience of this review document (TOC and project maintainers) already knows enough those. - // Some hardcoded text could be confusing. The ones that say "it can be this OR that OR something else". Maybe we can make them multiple choice inputs? - // Some parts can be explicitly marked as optional (points of excellence, etc.) - // Procedure to find out the number of substantial contributors - /// Review process need a "contact person" from the projct - // Make sure links to docs are to a specific commit - // I found "commit" column in "Documentation Content" section unnecessary as I wrote the repository commit I used to do the review at the top. - // Nothing about having a contributor guide (and a link to the governance in it) - // Nothing about the code of conduct - // Remove "Links" column in findings table - // Check employer affiliation in the mainainer list - // Some sections have explanations and some don't. - // How to assess the subprojects? What is the definition of it? How to know if there are notable divisions or not? - // Governance Improvements Suggestions Table - Review process flowchart/workflow + reviewer guide - Read governance - Compare it with the models TAG CS provides - Check PRs/issues/mailingList for public evidence of the usage of the governance - Check if there are links to the governance doc? From contributor guide, website, ... - Review cycle - TODO: feedback order: 1. TAG CS members --> no need for them to fix stuff 2. Project maintainers 3. TAG CS members again 4. TOC Liaison / TOC / etc. 5. ... - Self assessment / less experienced reviewers aspect - More numbers - More multiple choices - ... - Question based self assessment - Is your governance ...? - Has it ...? - Can it ...?