Merge pull request #2277 from cblecker/github-mgmt

GitHub Management Docs

7 files changed, 184 insertions, 48 deletions

diff --git a/CLA.md b/CLA.md
index 9672bf61..540ff4d5 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 00000000..9284fe78
--- /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
index 0651e3fb..7b1faf3b 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
index d0217f1d..ad7c8a7e 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 00000000..3ae03c70
--- /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
index bb344190..d679b804 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 02b52556..10d7b703 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)