Skip to content

Commit

Permalink
Update the GOVERNANCE.md per reviewer's comments till 2018/09/17
Browse files Browse the repository at this point in the history
Signed-off-by: Steven Zou <szou@vmware.com>
  • Loading branch information
steven-zou committed Sep 17, 2018
1 parent 89faa64 commit 266bfcb
Showing 1 changed file with 97 additions and 74 deletions.
171 changes: 97 additions & 74 deletions GOVERNANCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,70 +5,93 @@
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:

* **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 institutions of the whole 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.
* **Community Project Management:** Define the process to handle the community projects on top of harbor project.
* **Codebase Changes Management:** Define the process of handling codebase changes.

## Code Repositories

So far, 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.
* **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.

## Community Roles

The participants of harbor community may have different 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.
* **Partner**
* Partner MUST be a Harbor user first.
* Partner MUST be an organization which is listed in the PARTNER.md document.
* Partner HAS signed the brand usage authorization contact.
* **Contributor**
* Contributor is a GitHub user who HAS submitted at least one commit to harbor repositories.
* 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.
* Active contributor SHOULD be top **30** in the GitHub contributor rank list.
* 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**
* Member of TMB
* Strong willing to take more responsibilities of community management work
* Maintainer MUST be a active contributor
* Maintainer SHOULD be senior engineers (>5 service years)
* Member of TMB
* Generated by the nomination process.

## Technical Maintainer Board (TMB)

Technical maintainer board (TMB) is the top management institutions of the whole harbor community. TMB carries the mission of promoting and strengthening the community, grasps the development direction of the community and maintains the healthy growth of the community.
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

* Define and review the mission/roadmap of the project(s)
* Define and review the release plan
* Define and review the governance model/workflow of the community
* Review the tech proposals from community
* Review and approve PRs
* Review the maintainer joining requests
* Host the community calls
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

* Formed by `M+N` members
* N is an odd number between **5** and **15**, which is the total number of `maintainer`
* `maintainer` has full privileges of participating TMB activities
* M is the total number of `watcher`, no limitation
* `watcher` has limited privileges of participating TMB activities. They're in the pre-stage of becoming a formal maintainer. Follow and learn.
* **1** convener who takes charge of coordinating the TMB activities.
* 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 **1** vote
* `Watcher` has no vote
* A review request can be approved only and only if **2/3** members vote `YES`
* **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)
Expand All @@ -79,38 +102,29 @@ Technical maintainer board (TMB) is the top management institutions of the whole
* Update the status of the request to represent the right voting result
* Meet in TMB Regular calls and discuss general topics if necessary

### Membership
### Initial TMB members selection

* New member
* Nominated by existing member as a `maintainer` or `watcher` candidate
* Nomination is approved if getting **2/3** votes from the TMB
* Membership ending
* Quit by notifying the board with mails
* Persuade to quit if criteria is broken
* Tenure
* Full period is **1** year
* Document
* Memberships of maintainers are stored in the (MAINTAINER.md)[] document
* Renew
* If membership of one maintainer is ended in advance,
* Select a replacement candidate from the `watcher` list and **2/3** votes SHOULD be got after reviewing
* If no candidate in the `watcher` list, nominate 1 candidate from the active contributor list and **2/3** votes SHOULD be got after reviewing
* The replacement maintainer inherits the left membership tenure from the quitting maintainer
* If the full tenure is ended and the maintainer is still willing to be in,
* Renew the membership after getting **2/3** votes in the review
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.
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 feature
* System integration
* Additional tools
* New features
* System integrations
* Other innovation ideas

### Template
Expand All @@ -125,26 +139,23 @@ Each proposal should include clear and concrete descriptions of the following to
* The created time stamp
* The last updated time stamp
* The `epic` issue link with number if it is already under development
* The development team if it is already under development
* The motivations of or the related problem to the proposal
* The background of the proposal
* The technical background of the proposal
* The main idea of the proposal solution
* The architecture/design of the proposal solution
* The development plan of the proposal solution
* The resource plan of developing the proposal solution
* Additional contexts related with the proposal

Here is a good [proposal example](https://github.com/nlowe/harbor-tag-retention-proposal/blob/master/README.md).
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`.
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

To raise a proposal,

* Fork the [community](https://github.com/goharbor/community) repository to your namespace if you have not do that yet
* 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)
Expand All @@ -159,32 +170,44 @@ The proposal PR can be marked with different status labels to represent the stat
* **Accepted**: Proposal is reviewed and voted to accept
* **Rejected**: Proposal is reviewed but not enough votes got

If the status is marked to `Accepted`, the PR will be merged into the upstream repository and the proposal document is archived.
If the status is marked to `Accepted`, the PR will be merged into the upstream repository and the proposal document will be saved.

If the status is marked to `Rejected`, the PR will be directly closed, the proposal will be discarded.

If the `Accepted` proposal is pick up by community contributors to do the development work, a 'epic' issue should be created to drill down and track the related development tasks. The issue info should be updated to the proposal document.
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.

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:

* The implemented code is merged to the branches of the governed repositories via PRs
* Or it is implemented as an independent [community project](#community-project-management) and linked in the official website and README files as additional tools
* The implemented code is merged to the codebase of the governed repositories via PRs

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.

The proposals under the root of the `proposal` folder 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.
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.

Adhoc picking up should not be supported now.

## Community Project Management
## Codebase Changes Management

Any changes to the codebase of governed repositories MUST be done through the PRs.

* 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

A community project is an independent repository under an external namespace and maintained by the owners themselves. The community project contains the implementation of one specified proposal but the implementation can not be merged or integrated as native feature for some reasons so far. It will be run as an additional external tools to provide some extended capabilities on top of the governed projects.
### Community project onboarding PR

## Basic flow
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.

Once the development work of the community project is finished and ready to be published to the community for trying,
Once the development work of the community project is finished and ready to be published to the community for adopting,

* 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.
* 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.

```
* [name of the community project](link of repo url)
Expand All @@ -193,5 +216,5 @@ Once the development work of the community project is finished and ready to be p
```

* The TMB will review the PR and make decision via voting
* If voting passed (**2/3 YES**), the updates will be merged. That means the project is onboared to harbor community
* If voting failed, the onboarding request will be rejected. PR will be directly closed.
* 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.

0 comments on commit 266bfcb

Please sign in to comment.