-
Notifications
You must be signed in to change notification settings - Fork 82
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Update the governace model doc per comments till 2018/09/21
Signed-off-by: Steven Zou <szou@vmware.com>
- Loading branch information
1 parent
266bfcb
commit e0232f7
Showing
2 changed files
with
45 additions
and
191 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,220 +1,75 @@ | ||
| # Governance Constitution | ||
| # Harbor Governance | ||
|
|
||
| ## Overview | ||
| This document defines the project governance for Harbor. | ||
|
|
||
| Harbor is committed to building an open, evolutionary, high-efficiency and self-governance OSS community to provide cloud-native registry relevant tools and services. The whole community is run and managed by this constitution including the following chapters: | ||
| ## Overview | ||
|
|
||
| * **Code Repositories:** List the code repositories governed by Harbor community. | ||
| * **Community Roles:** Define roles of Harbor community affiliated parties. | ||
| * **Technical Maintainer Board:** Define how to build and how does the technical maintainer board work, which is the top management institution of the whole community. | ||
| * **Proposal Management:** How to manage the proposals and plan the new release. | ||
| * **Codebase Changes Management:** Define the process of handling codebase changes. | ||
| **Harbor**, a Cloud Native Computing Foundation (CNCF) project, is committed to building an open, inclusive, productive and self-governing open source community focused on building a high-quality cloud native registry. The community is governed by this document with the goal of defining how community should work together to achieve this goal. | ||
|
|
||
| ## Code Repositories | ||
|
|
||
| So far, the following code repositories are governed by Harbor community and maintained under the `goharbor` namespace. | ||
| The following code repositories are governed by Harbor community and maintained under the `goharbor` namespace. | ||
|
|
||
| * **Harbor:** The code base of Harbor registry project. | ||
| * **Harbor-helm:** The helm chart of the Harbor registry. | ||
| * **community:** A repository to keep community related material like proposals, introduction slides, community governance documents and community meeting minutes etc. | ||
| * **Harbor:** Main Harbor codebase. | ||
| * **Harbor-helm:** Helm chart for easy deployment of Harbor | ||
| * **community:** Used to store community-related material–e.g., proposals, presentation slides, governance documents, community meeting minutes, etc. | ||
|
|
||
| ## Community Roles | ||
|
|
||
| The participants of Harbor community may have different roles: | ||
|
|
||
| * **User** | ||
| * User IS a person or an organization adopting and using Harbor as cloud-native registry. | ||
| * **Contributor** | ||
| * Contributor is a GitHub user who HAS at least one commit merged to Harbor repositories. | ||
| * **Active Contributor** | ||
| * Active contributor MUST be a contributor first. | ||
| * Active contributor SHOULD have continuous contributions in a reasonable period (e.g: a release period). | ||
| * Active contributor SHOULD be top **30** in the GitHub contributor rank list of the governed repositories. | ||
| * **Maintainer** | ||
| * Strong willing to take more responsibilities of community management work | ||
| * Maintainer MUST be a active contributor | ||
| * Member of TMB | ||
| * Generated by the nomination process. | ||
|
|
||
| ## Technical Maintainer Board (TMB) | ||
|
|
||
| Technical maintainer board (TMB) is the top management institution of the whole Harbor community. TMB carries the mission of promoting and strengthening the community, leading the development direction of the community and maintaining the healthy growth of the community. | ||
|
|
||
| ### Responsibilities | ||
|
|
||
| The Harbor community maintainers are responsible for: | ||
|
|
||
| * Maintaining the mission, vision, values and roadmap of the project(s) | ||
| * Refining the governance model/workflow of the community if needed | ||
| * Defining and reviewing the release plan | ||
| * Reviewing the tech proposals from community | ||
| * Controlling the PRs | ||
| * Handling code of conduct violations | ||
| * Deciding what community projects can be referred by Harbor | ||
| * Managing the memberships of TMB | ||
| * Hosting the community calls | ||
| * Any other community-related stuff needs decision making | ||
|
|
||
| ### Scale and Structure | ||
|
|
||
| * TMB is formed by `M` maintainers, `M` is an odd number between **5** and **15**. | ||
| * **One** of the maintainer will take the convener role to coordinate the TMB related activities. | ||
|
|
||
| ### Membership | ||
|
|
||
| The following principles are applied to manage the membership of the TMB: | ||
|
|
||
| * New member | ||
| * Nominated by an existing member as a `maintainer` candidate | ||
| * Nomination should be reviewed and approved by TMB via **[voting](#work-process)** | ||
| * Tenure | ||
| * The membership has limited tenure | ||
| * Full period is **2** years | ||
| * Membership ending | ||
| * Step down by notifying the board with mails | ||
| * If the maintainer criteria is broken, a **[voting](#work-process)** should be raised to determine whether or not end the membership. | ||
| * Renew | ||
| * If membership of one maintainer is ended in advance, | ||
| * Get a backfill by triggering the `New member` process. | ||
| * If the full tenure is ended and the maintainer is still willing to be in, | ||
| * The membership can be renewed after reviewing. | ||
| * Document | ||
| * Memberships of maintainers are stored in the [MAINTAINER.md][./MAINTAINER.md] document | ||
|
|
||
| ### Work Process | ||
|
|
||
| * **Voting** is the primary way to make decision in TMB | ||
| * Each `maintainer` of TMB has only **1** vote | ||
| * Two different approval models are supported to cover the review requests with different weight | ||
| * **[super-majority](https://en.wikipedia.org/wiki/Supermajority#Two-thirds_vote) vote**: A review request can be approved only and only more than **2/3** maintainers vote `YES`. The follow topics should follow this model: | ||
| * Changes to mission, vision, values and roadmap of the project(s) | ||
| * Changes to governance model/workflow of the community | ||
| * Release plan | ||
| * **[majority vote](https://en.wikipedia.org/wiki/Majority#Majority_vote) vote**: A review request can be approved only and only more than **1/2** maintainers vote `YES`: | ||
| * All other topics excluding above ones can follow this model | ||
| * Follow the below process to review community topics | ||
| * Convener or a maintainer originates a review request with any of the following ways | ||
| * TMB IM channel (private slack channel #harbor-maintainers under CNCF workspace) | ||
| * TMB maillist (harbor-maintainers@googlegroups.com) | ||
| * TMB Regular calls | ||
| * Discuss and comment the review request | ||
| * Launch a vote activity and collect voting results by the request originator | ||
| * Update the status of the request to represent the right voting result | ||
| * Meet in TMB Regular calls and discuss general topics if necessary | ||
|
|
||
| ### Initial TMB members selection | ||
|
|
||
| The maintainers of initial TMB are from the following different sources: | ||
|
|
||
| * **4** from VMware Harbor founder team | ||
| * **3** from active contributors of different organizations | ||
| * **1** from CaiCloud | ||
| * **1** from HylandSoftware | ||
| * **1** from Tencent | ||
|
|
||
| This accounts for a total of **7** initial maintainers. | ||
|
|
||
| ## Proposal Management | ||
|
|
||
| Proposal is the only way to request applying changes to the projects governed by the Harbor community. The project release plans should also be built based on the `accepted` proposals. | ||
|
|
||
| ### Scope | ||
|
|
||
| A proposal can cover one of the following different kinds of change requests: | ||
|
|
||
| * Changes/enhancements to the existing features | ||
| * New features | ||
| * System integrations | ||
| * Other innovation ideas | ||
|
|
||
| ### Template | ||
|
|
||
| Each proposal should include clear and concrete descriptions of the following topics: | ||
|
|
||
| * Header | ||
| * The authors of the proposal | ||
| * GitHub ID | ||
| * company name if have | ||
| * The created time stamp | ||
| * The last updated time stamp | ||
| * The `epic` issue link with number if it is already under development | ||
| * The motivations of or the related problem to the proposal | ||
| * The technical background of the proposal | ||
| * The main idea of the proposal solution | ||
| * The architecture/design of the proposal solution | ||
| * Additional contexts related with the proposal | ||
|
|
||
| Here is a good [proposal example](https://github.com/goharbor/community/pull/4). | ||
|
|
||
| ### Format | ||
|
|
||
| The proposal should be documented as a separated markdown file containing the relevant sections described in the above [Template](#template) chapter and pushed to the `proposals` folder in the [community](https://github.com/goHarbor/community) repository via PR. The name of the file should follow the name pattern `<short meaningful words joined by '-'>_proposal.md`, e.g: `clear-old-tags-with-policies_proposal.md`. | ||
|
|
||
| ### Work flow | ||
| * **Users:** members that engage with the Harbor community via any medium (Slack, WeChat, GitHub, mailing lists, etc.) | ||
| * **Contributors:** regular contributions to projects (documentation, code reviews, responding to issues, participation in proposal discussions, contributing code, etc.). Two levels of maintainership are defined below. | ||
| * **Maintainers**: see definitions and distinction below | ||
|
|
||
| To raise a proposal, | ||
| ## Project Leadership | ||
|
|
||
| * Fork the [community](https://github.com/goHarbor/community) repository to your namespace if you have not do that yet | ||
| * Sync the main branch of your forked repository with the upstream repository to confirm merging the latest updates | ||
| * Create a new branch to track your work | ||
| * Create a new markdown file with a proper name and complete the contents by following the above specs defined in [Template](#template) | ||
| * Raise a new PR to the upstream `master` branch with proper comments | ||
|
|
||
| The TMB will pick up the submitted PR at proper time and start the discussion and reviewing process. The related comments will be posted under the PR. The authors of the proposal should continuously apply changes to the PR if required by the TMB and the authors accept it. If authors have different opinions, they can discuss it with the TMD in the comment threads of the PR. | ||
| There are two roles that convey project leadership: maintainers and core maintainers. | ||
|
|
||
| The proposal PR can be marked with different status labels to represent the status of the proposal: | ||
| * **Core Maintainers**: Responsible for the overall health and direction of the project; final reviewers of PRs and responsible for releases. | ||
| * **Maintainers**: Responsible for one or more components within a project, and are expected to contribute code and documentation, review PRs including ensuring quality of code, triage issues, proactively fix bugs, and perform maintenance tasks for these components. | ||
|
|
||
| * **New**: Proposal is just created | ||
| * **Reviewing**: Proposal is under reviewing and discussion | ||
| * **Accepted**: Proposal is reviewed and voted to accept | ||
| * **Rejected**: Proposal is reviewed but not enough votes got | ||
| ### Supermajority | ||
|
|
||
| A supermajority is defined as two-thirds of members in the group (e.g., non-core maintainers or core maintainers) that require the majority. | ||
|
|
||
| If the status is marked to `Accepted`, the PR will be merged into the upstream repository and the proposal document will be saved. | ||
| ### Total Maintainership | ||
|
|
||
| If the status is marked to `Rejected`, the PR will be directly closed, the proposal will be discarded. | ||
| Total maintainership is defined as the union of maintainers and core maintainers. | ||
|
|
||
| If the `Accepted` proposal is pick up by community contributors to do the development work, an `epic` issue should be created to drill down and track the related development tasks. The issue info should be updated to the proposal document. | ||
| ### Maintainers | ||
|
|
||
| If the proposal is successfully implemented and delivered, the related proposal document should be moved to the `delivered` sub folder under the `proposal` folder. Proposal being delivered means: | ||
| New maintainers must be nominated by an existing maintainer or core maintainer and must be elected by a supermajority of total maintainership. Likewise, maintainers can be removed by a supermajority of the total maintainership or can resign by notifying the core maintainers. | ||
|
|
||
| * The implemented code is merged to the codebase of the governed repositories via PRs | ||
| ### Core Maintainers | ||
|
|
||
| If the proposal is failed to deliver for some reasons, the related proposal document should be moved to the `failed` sub folder under the `proposal` folder. | ||
| Nomination for core maintainership requires (a) a nomination by an existing core maintainer, and (b) election by a supermajority of the core maintainer group. Likewise, maintainers can be removed by a supermajority core maintainer vote or can resign by notifying the core maintainers. | ||
|
|
||
| The proposals under the sub folder `new` can be treated as a proposal pool, community contributors can pick up from this pool if they want to do contributions to Harbor community when creating the release plan. | ||
| ### Decision Making | ||
|
|
||
| Adhoc picking up should not be supported now. | ||
| Ideally, all project decisions are resolved by consensus. If impossible, any maintainer may call a vote. Unless otherwise specified in this document, any vote will be decided by a supermajority of the total maintainership, with a requirement of at least one core maintainer voting. | ||
|
|
||
| ## Codebase Changes Management | ||
| Votes by maintainers (either core or non-core) belonging to the same company will count as one vote; e.g., 4 maintainers employed by company `${x}` will only have **one** combined vote. | ||
|
|
||
| Any changes to the codebase of governed repositories MUST be done through the PRs. | ||
| ## Proposal Process | ||
|
|
||
| * The PRS should match the following criteria: | ||
| * PR MUST have concrete and clear description of what work has been done in the PR | ||
| * All the commits under the PR SHOULD target the same work declared in the above description | ||
| * All the commits under the PR MUST have [meaningful commit messages](http://chris.beams.io/posts/git-commit/). | ||
| * All the checks SHOULD passed | ||
| * DCO check (required) | ||
| * CI/CD pipelines (required) | ||
| * Codacy quality review (optional) | ||
| * The PRs can be reviewed and commented by any community contributors | ||
| * The PRs can be only approved and merged with at least **2** approvals of maintainers | ||
| One of the most important aspects in any open source community is the concept of proposals. Large changes to the codebase and / or new features should be preceded by a proposal in our community repo. This process allows for all members of the community to weigh in on the concept (including the technical details), share their comments and ideas, and even offer to help. It also ensures that members are not duplicating work or inadvertently stepping on toes by making large conflicting changes. | ||
|
|
||
| ### Community project onboarding PR | ||
| The project roadmap is defined by accepted proposals. | ||
|
|
||
| A community project is an independent repository under an external namespace and maintained by the owners themselves. It will be run as an additional external tools to provide some extended capabilities on top of the governed projects. | ||
| Proposals should cover the high-level objectives, use cases, and technical recommendations on how to implement. In general, the community member interested in implementing the proposal should be either deeply engaged in the proposal process or be the author of the proposal {him,her}self. | ||
|
|
||
| Once the development work of the community project is finished and ready to be published to the community for adopting, | ||
| The proposal should be documented as a separated markdown file pushed to the `proposals` folder in the [community](https://github.com/goHarbor/community) repository via PR. The name of the file should follow the name pattern `<short meaningful words joined by '-'>_proposal.md`, e.g: `clear-old-tags-with-policies_proposal.md`. | ||
|
|
||
| * Raise a PR to update the [Additional Tools](https://github.com/goHarbor/Harbor#additional-tools) section in the [Harbor](https://github.com/goHarbor/Harbor) repository by appending the contents with below pattern. | ||
| See this [PR](https://github.com/goharbor/community/pull/4) as a good example of a proposal. | ||
|
|
||
| ### Proposal Lifecycle | ||
|
|
||
| The proposal PR can be marked with different status labels to represent the status of the proposal: | ||
|
|
||
| * **New**: Proposal is just created | ||
| * **Reviewing**: Proposal is under reviewing and discussion | ||
| * **Accepted**: Proposal is reviewed and voted to accept | ||
| * **Rejected**: Proposal is reviewed but not enough votes got | ||
|
|
||
| ``` | ||
| * [name of the community project](link of repo url) | ||
| * <The main feature this project provides> | ||
| * Lead by <GitHub ID of the author> from <company name> | ||
| ``` | ||
| ## Updating Governance | ||
|
|
||
| * The TMB will review the PR and make decision via voting | ||
| * If [voting](#work-process) passed, the updates will be merged. That means the project is onboared to Harbor community | ||
| * If [voting](#work-process) failed, the onboarding request will be rejected. PR will be directly closed. | ||
| All changes in Governance require a supermajority total organizational (non-core + core maintainers) vote. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters