diff --git a/CLA.md b/CLA.md index 9672bf613..540ff4d5b 100644 --- a/CLA.md +++ b/CLA.md @@ -85,5 +85,5 @@ Someone from the CNCF will respond to your ticket to help. ## Setting up the CNCF CLA check If you are a Kubernetes GitHub organization or repo owner, and would like to setup -the Linux Foundation CNCF CLA check for your repositories, please -[read the docs on setting up the CNCF CLA check](/setting-up-cla-check.md) +the Linux Foundation CNCF CLA check for your repositories, please +[read the docs on setting up the CNCF CLA check](/github-management/setting-up-cla-check.md) diff --git a/github-management/README.md b/github-management/README.md new file mode 100644 index 000000000..9284fe78a --- /dev/null +++ b/github-management/README.md @@ -0,0 +1,70 @@ +# GitHub Management + +The Kubernetes project uses Github extensively to store and organize code, +manage issues and documentation, and provide a consistent contributor flow. + +With the size and growth of the Kubernetes project, management of our Github +footprint has historically been a challenge. We have created a number of +policies to reduce friction and ease administration of our Github repositories +and organizations. We have also created a number of tools to automate setup and +enforcement of these policies. + +## Guides +- [Organization Owners Guide](org-owners-guide.md) +- [Repository Creation Guidelines](kubernetes-repositories.md) +- [Setting up the CNCF CLA Check](setting-up-cla-check.md) +- [GitHub Permissions](permissions.md) + +## Project Owned Organizations + +The following organizations are currently known to be part of the Kubernetes +project + +### Actively used GitHub Organizations + +| Name | Description | +| :--: | :---------: | +| [kubernetes](https://github.com/kubernetes) | Core | +| [kubernetes-client](https://github.com/kubernetes-client) | API Client Libraries | +| [kubernetes-csi](https://github.com/kubernetes-csi) | Container Storage Interface Components | +| [kubernetes-incubator](https://github.com/kubernetes-incubator) | Legacy Incubator Projects | +| [kubernetes-retired](https://github.com/kubernetes-retired) | Retired/Archived Projects | +| [kubernetes-security](https://github.com/kubernetes-security) | Private Security Fix Mirror | +| [kubernetes-sigs](https://github.com/kubernetes-sigs) | SIG-related Projects | + +### Non-actively used GitHub Organizations + +| Name | Description | +| :--: | :---------: | +| [kubernetes-addons](https://github.com/kubernetes-addons) | | +| [kubernetes-charts](https://github.com/kubernetes-charts) | | +| [kubernetes-extensions](https://github.com/kubernetes-extensions) | | +| [kubernetes-federation](https://github.com/kubernetes-federation) | | +| [kubernetes-graveyard](https://github.com/kubernetes-graveyard) | kubernetes-retired should be used instead going forward | +| [kubernetes-incubator-retired](https://github.com/kubernetes-incubator-retired) | kubernetes-retired should be used instead going forward | +| [kubernetes-providers](https://github.com/kubernetes-providers) | | +| [kubernetes-sidecars](https://github.com/kubernetes-sidecars) | | +| [kubernetes-sig-testing](https://github.com/kubernetes-sig-testing) | | +| [kubernetes-test](https://github.com/kubernetes-test) | | +| [kubernetes-tools](https://github.com/kubernetes-tools) | | + +Note, this list is subject to change. + +There are more organization names that we are squatting on with possible future +intentions. [For more details please see community issue #1407](https://github.com/kubernetes/community/issues/1407). + +## Tooling + +We have created a number of tools to help with the management of or Github +repositories and organizations: +- [prow](https://git.k8s.io/test-infra/prow): Prow is our system for handling + GitHub events and commands for Kubernetes. It is comprised of a number of + modules/plugins. A couple key ones for GitHub management are below, but a full + list of commands is available [here](https://go.k8s.io/bot-commands) + - [branchprotector](https://git.k8s.io/test-infra/prow/cmd/branchprotector): + enforce branch protection settings across an organization + - [peribolos](https://git.k8s.io/test-infra/prow/cmd/peribolos): Manage Github + organization and team membership based on a defined YAML configuration +- [label_sync](https://git.k8s.io/test-infra/label_sync): Add, modify, delete, + and migrate labels across an entire organization based on a defined YAML + configuration diff --git a/kubernetes-repositories.md b/github-management/kubernetes-repositories.md similarity index 97% rename from kubernetes-repositories.md rename to github-management/kubernetes-repositories.md index 0651e3fb2..7b1faf3b0 100644 --- a/kubernetes-repositories.md +++ b/github-management/kubernetes-repositories.md @@ -1,7 +1,6 @@ -## Kubernetes Repositories +## Kubernetes Repository Guidelines - -This document attempts to outline a structure for creating and associating github repositories with the Kubernetes project. It also describes how and when +This document attempts to outline a structure for creating and associating GitHub repositories with the Kubernetes project. It also describes how and when repositories are removed. The document presents a tiered system of repositories with increasingly strict requirements in an attempt to provide the right level of oversight and flexibility for a variety of different projects. @@ -83,7 +82,7 @@ that our various projects and repositories are active and healthy. This ensures that repositories are kept up to date with the latest Kubernetes wide processes, it ensures a rapid response to potential required fixes (e.g. critical security problems) and (most importantly) it ensures that -contributors and users receive quick feedback on their issues and +contributors and users receive quick feedback on their issues and contributions. #### Grounds for removal @@ -91,7 +90,7 @@ SIG repositories and core repositories may be removed from the project if they are deemed _inactive_. Inactive repositories are those that meet any of the following criteria: - * There are no longer any active maintainers for the project and no + * There are no longer any active maintainers for the project and no replacements can be found. * All PRs or Issues have gone un-addressed for longer than six months. * There have been no new commits or other changes in more than a year. @@ -102,8 +101,8 @@ circumstances (e.g. a code of conduct violation). #### Procedure for removal -When a repository is set for removal, it is moved into the -[kubernetes-retired](https://github.com/kubernetes-retired) organization. +When a repository is set for removal, it is moved into the +[kubernetes-retired](https://github.com/kubernetes-retired) organization. This maintains the complete record of issues, PRs and other contributions, but makes it clear that the repository should be considered archival, not active. We will also diff --git a/org-owners-guide.md b/github-management/org-owners-guide.md similarity index 61% rename from org-owners-guide.md rename to github-management/org-owners-guide.md index d0217f1d7..ad7c8a7ec 100644 --- a/org-owners-guide.md +++ b/github-management/org-owners-guide.md @@ -1,4 +1,4 @@ -# Kubernetes Github Organization Guide +# Kubernetes GitHub Organization Guide The Kubernetes project leverages multiple GitHub organizations to store and organize code. This guide contains the details on how to run those organizations @@ -26,40 +26,6 @@ contact the steering committee and CNCF prior to moving any code in. It is easier to start new code in a Kubernetes organization than it is to transfer in existing code. -## Current Organizations In Use - -The following organizations are currently known to be part of the Kubernetes -project: - -### Actively used GitHub Organizations: -* [kubernetes](https://github.com/kubernetes) -* [kubernetes-client](https://github.com/kubernetes-client) -* [kubernetes-csi](https://github.com/kubernetes-csi) -* [kubernetes-incubator](https://github.com/kubernetes-incubator) -* [kubernetes-retired](https://github.com/kubernetes-retired) -* [kubernetes-security](https://github.com/kubernetes-security) -* [kubernetes-sig-testing](https://github.com/kubernetes-sig-testing) -* [kubernetes-sigs](https://github.com/kubernetes-sigs) - -### Non-actively used GitHub Organizations: -* [kubernetes-addons](https://github.com/kubernetes-addons) -* [kubernetes-charts](https://github.com/kubernetes-charts) -* [kubernetes-extensions](https://github.com/kubernetes-extensions) -* [kubernetes-federation](https://github.com/kubernetes-federation) -* [kubernetes-graveyard](https://github.com/kubernetes-graveyard) † -* [kubernetes-incubator-retired](https://github.com/kubernetes-incubator-retired) -* [kubernetes-providers](https://github.com/kubernetes-providers) -* [kubernetes-sidecars](https://github.com/kubernetes-sidecars) -* [kubernetes-test](https://github.com/kubernetes-test) -* [kubernetes-tools](https://github.com/kubernetes-tools) - -† kubernetes-retired should be used instead of kubernetes-graveyard going forward. - -Note, this list is subject to change. - -There are more organization names that we are squatting on with possible future -intentions. [For more details please see community issue #1407](https://github.com/kubernetes/community/issues/1407). - ## Team Guidance Each organization should have the following teams: @@ -93,4 +59,4 @@ for all orgs going forward. Notable discrepancies at the moment: Repositories have additional guidelines and requirements, such as the use of CLA checking on all contributions. For more details on those please see the -[Kubernetes Template Project](https://github.com/kubernetes/kubernetes-template-project). +[Kubernetes Template Project](https://github.com/kubernetes/kubernetes-template-project), and the [Repository Guidelines](kubernetes-repositories.md) diff --git a/github-management/permissions.md b/github-management/permissions.md new file mode 100644 index 000000000..3ae03c70a --- /dev/null +++ b/github-management/permissions.md @@ -0,0 +1,101 @@ +# GitHub Permissions + +GitHub provides a limited permissions model for organizations and repositories. +It lacks granularity, and for the most part is "all or nothing". This doesn't +scale well with the size and velocity of the Kubernetes project. + +We have created a number of automated systems/bots to allow us to work around +these limitations. Authorized users can issue [bot commands] to execute actions +against PRs and issues without having direct GitHub access to run these +actions. [OWNERS] files are used to gate approvals to merge, and most merges are +handled by automation. This allows us the flexibility to delegate access to +small or large groups of users, without providing direct write or admin access. + +That said, there are some actions that are so infrequent, or so complex that +automation isn't a good fit. There is also a need for a small set of users that +can act as a backstop for setting up and maintaining this automation, and +manual intervention if needed. + +## Organization Level Permissions + +GitHub provides [two access levels][org permissions] to an organization: owner, +and member. + +### Owner + +Organization owners have full access to the organization, including the ability +to modify billing information and even delete the entire organization. +Therefore, we are very cautious about giving more people this access than +really need it. + +There are certain actions that require org owner access: +- Invite or remove members from the organization (in future, will be handled by + [peribolos]) +- Access the organization audit log +- Create new repositories +- Transfer repositories +- Approve GitHub application integrations + +**// TODO(cblecker):** Define specific roles that need this. + +### Member + +Organization members are granted "read" access to all repositories in the org, +are able to be assigned issues and PRs, and are able to mention and join +teams. This is the base level of access to an organization. + +A our automation tools look for organization membership as a permissions level +for running certain bot commands. The [bot commands] list details which +commands are restricted to org members. + +Org membership is granted as a part of becoming a member of the Kubernetes +community as defined in the [community membership] document. + +## Repository Level Permissions + +GitHub provides [three access levels][repo permissions] to a repository: admin, +write, and read. + +### Admin + +A repository admin has full access to the repository, and is able to modify any +repository-scoped setting, including renaming or deleting a repository, +manually merge code, and override/change branch protection settings. This is a +trusted role, and should only be given to a limited number of senior +maintainers of a repository. + +In most cases, this level of access should not be necessary as the majority of +actions will be able to be implemented by automation. Certain actions like +creating a release may still need this level of access. + +**// TODO(cblecker):** Define specific roles that need this. + +### Write + +Providing direct write access to a repository exposes a number of settings that +are not normally available, including: +- The ability to manually add and remove labels from issues/PRs +- The ability to push new branches +- Manually open and close issues/PRs + +While users with write access cannot override branch protection settings and +manually merge PRs, they can manually apply labels like `lgtm`/`approve`, +bypassing normal processes. Write access is being phased out as the majority +of actions are implemented via automation. + +### Read + +This is the default level of access that is provided to org members on every +repo in the organization. Read access allows you to be assigned issues and PRs +in the repository, but that's about it. It is provided by default to every +member in the organization. + + +[bot commands]: https://go.k8s.io/bot-commands +[community membership]: /community-membership.md +[org permissions]: +https://help.github.com/articles/permission-levels-for-an-organization/ +[OWNERS]: /contributors/guide/owners.md +[peribolos]: https://git.k8s.io/test-infra/prow/cmd/peribolos +[repo permissions]: +https://help.github.com/articles/repository-permission-levels-for-an-organization/ diff --git a/setting-up-cla-check.md b/github-management/setting-up-cla-check.md similarity index 96% rename from setting-up-cla-check.md rename to github-management/setting-up-cla-check.md index bb3441904..d679b8040 100644 --- a/setting-up-cla-check.md +++ b/github-management/setting-up-cla-check.md @@ -13,7 +13,7 @@ the Linux Foundation CNCF CLA check for your repositories, please read on. - Payload URL: https://identity.linuxfoundation.org/lfcla/github/postreceive?group=284&comment=no&target=https://identity.linuxfoundation.org/projects/cncf - `group=284` specifies the ID of the CNCF project authorized committers group in our CLA system. - `comment=no` specifies that our system should not post help comments into the pull request (since the Kubernetes mungebot does this). - - `target=https://identity.linuxfoundation.org/projects/cncf` specifies what will be used for the "Details" link in Github for this status check. + - `target=https://identity.linuxfoundation.org/projects/cncf` specifies what will be used for the "Details" link in GitHub for this status check. - Content Type: 'application/json' - Secret: Please contact [@idvoretskyi](mailto:ihor@cncf.io), and [@caniszczyk](mailto:caniszczyk@linuxfoundation.org). - Events: Let me select individual events @@ -56,5 +56,5 @@ the same org/repo, to ensure that it can add labels `cncf-cla: yes` and `cncf-cl on the status published by the Linux Foundation webhook. The label automation may not be essential for your repository, if you’re not using merge -automation. For repos with maintainers doing manual merges, github protected branches may +automation. For repos with maintainers doing manual merges, GitHub protected branches may suffice. diff --git a/incubator.md b/incubator.md index 02b52556e..10d7b7036 100644 --- a/incubator.md +++ b/incubator.md @@ -1,6 +1,6 @@ # IMPORTANT - The Kubernetes Incubator process is now deprecated and has been superseded by Kubernetes subprojects -For information on creating a repository for a subproject see: [kubernetes-repositories](kubernetes-repositories.md) +For information on creating a repository for a subproject see: [kubernetes-repositories](/github-management/kubernetes-repositories.md) Each SIG should define the process for sponsoring new subprojects in its charter. For information on SIG governance and charters see: [SIG governance](committee-steering/governance/README.md)