Move existing github related docs to dedicated folder

3 files changed, 313 insertions, 0 deletions

diff --git a/github-management/kubernetes-repositories.md b/github-management/kubernetes-repositories.md
new file mode 100644
index 00000000..0651e3fb
--- /dev/null
+++ b/github-management/kubernetes-repositories.md
@@ -0,0 +1,157 @@
+## Kubernetes Repositories
+
+
+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.
+
+### Associated Repositories
+
+Associated repositories conform to the Kubernetes community standards for a repository, but otherwise have no restrictions. Associated repositories exist solely for the purpose of making it easier for the Kubernetes community to work together. There is no implication of support or endorsement of any kind by the Kubernetes project, the goals are purely logistical.
+
+#### Goals
+
+To facilitate contributions and collaboration from the broader Kubernetes community.  Contributions to random projects with random CLAs (or DCOs) can be logistically difficult, so associated repositories should be easier.
+
+
+#### Rules
+
+   * Must adopt the Kubernetes Code of Conduct statement in their repo.
+   * All code projects use the Apache License version 2.0. Documentation repositories must use the Creative Commons License version 4.0.
+   * Must adopt the CNCF CLA bot automation for pull requests.
+
+
+### SIG repositories
+
+SIG repositories serve as temporary homes for SIG-sponsored experimental projects or prototypes of new core functionality, or as permanent homes for SIG-specific tools.
+
+#### Goals
+
+To provide a place for SIGs to collaborate on projects endorsed by and actively worked on by members of the SIG. SIGs should be able to approve and create new repositories for SIG-sponsored projects without requiring higher level approval from a central body (e.g. steering committee or sig-architecture)
+
+#### Rules for new repositories
+
+   * For now all repos will live in github.com/kubernetes-sigs/\<project-name\>.
+   * Must contain the topic for the sponsoring SIG - e.g. `k8s-sig-api-machinery`.  (Added through the *Manage topics* link on the repo page.)
+   * Must adopt the Kubernetes Code of Conduct
+   * All code projects use the Apache License version 2.0. Documentation repositories must use the Creative Commons License version 4.0.
+   * Must adopt the CNCF CLA bot, merge bot and Kubernetes PR commands/bots.
+   * All OWNERS of the project must also be active SIG members.
+   * SIG membership must vote using lazy consensus to create a new repository
+   * SIG must already have identified all of their existing subprojects and code, with valid OWNERS files, in [`sigs.yaml`](https://github.com/kubernetes/community/blob/master/sigs.yaml)
+
+#### Rules for donated repositories
+
+The `kubernetes-sigs` organization is primarily intended to house net-new
+projects originally created in that organization. However, projects that a SIG
+adopts may also be donated.
+
+In addition to the requirements for new repositories, donated repositories must demonstrate that:
+
+   * All contributors must have signed the [CNCF Individual CLA](https://github.com/cncf/cla/blob/master/individual-cla.pdf)
+   or [CNCF Corporate CLA](https://github.com/cncf/cla/blob/master/corporate-cla.pdf)
+   * If (a) contributor(s) have not signed the CLA and could not be reached, a NOTICE
+   file should be added referencing section 7 of the CLA with a list of the developers who could not be reached
+   * Licenses of dependencies are acceptable; project owners can ping [@caniszczyk](https://github.com/caniszczyk) for review of third party deps
+   * Boilerplate text across all files should attribute copyright as follows: `"Copyright <Project Authors>"` if no CLA was in place prior to donation
+
+### Core Repositories
+
+Core repositories are considered core components of Kubernetes. They are utilities, tools, applications, or libraries that are expected to be present in every or nearly every Kubernetes cluster, such as components and tools included in official Kubernetes releases. Additionally, the kubernetes.io website, k8s.io machinery, and other project-wide infrastructure will remain in the kubernetes github organization.
+
+#### Goals
+Create a broader base of repositories than the existing gh/kubernetes/kubernetes so that the project can scale. Present expectations about the centrality and importance of the repository in the Kubernetes ecosystem. Carries the endorsement of the Kubernetes community.
+
+#### Rules
+
+   * Must live under `github.com/kubernetes/<project-name>`
+   * Must adopt the Kubernetes Code of Conduct
+   * All code projects use the Apache Licence version 2.0. Documentation repositories must use the Creative Commons License version 4.0.
+   * Must adopt the CNCF CLA bot
+   * Must adopt all Kubernetes automation (e.g. /lgtm, etc)
+   * All OWNERS must be members of standing as defined by ability to vote in Kubernetes steering committee elections. in the Kubernetes community
+   * Repository must be approved by SIG-Architecture
+
+### Removing Repositories
+
+As important as it is to add new repositories, it is equally important to
+prune old repositories that are no longer relevant or useful.
+
+It is in the best interests of everyone involved in the Kubernetes community
+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 
+contributions.
+
+#### Grounds for removal
+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 
+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.
+
+Associated repositories are much more loosely associated with the Kubernetes
+project and are generally not subject to removal, except under exceptional
+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. 
+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
+use the [github archive feature](https://help.github.com/articles/archiving-a-github-repository/) to mark the repository as archival and read-only.
+
+The decision to archive a repository will be made by SIG architecture and
+announced on the Kubernetes dev mailing list and community meeting.
+
+### FAQ
+
+*My project is currently in kubernetes-incubator, what is going to happen to it?*
+
+Nothing. We’ll grandfather existing projects and they can stay in the incubator org for as long as they want to. We expect/hope that most projects will either move out to ecosystem, or into SIG or Core repositories following the same approval process described below.
+
+
+
+*My project wants to graduate from incubator, how can it do that?*
+
+Either approval from a SIG to graduate to a SIG repository, or approval from SIG-Architecture to graduate into the core repository.
+
+
+
+*My incubator project wants to go GA, how can it do that?*
+
+For now, the project determines if and when it is GA. For the future, we may define a cross Kubernetes notion of GA for core and sig repositories, but that’s not in this proposal.
+
+
+
+*My project is currently in core, but doesn’t seem to fit these guidelines, what’s going to happen?*
+
+For now, nothing. Eventually, we may redistribute projects, but for now the goal is to adapt the process going forward, not re-legislate past decisions.
+
+
+
+*I’m starting a new project, what should I do?*
+
+Is this a SIG-sponsored project? If so, convince some SIG to host it, take it to the SIG mailing list, meeting and get consensus, then the SIG can create a repo for you in the SIG organization.
+
+
+
+Is this a small-group or personal project? If so, create a repository wherever you’d like, and make it an associated project.
+
+
+
+We suggest starting with the kubernetes-template-project to ensure you have the correct code of conduct, license, etc.
+
+
+
+*Much of the things needed (e.g. CLA Bot integration) is missing to support associated projects. Many things seem vague. Help!*
+
+True, we need to improve these things. For now, do the best you can to conform to the spirit of the proposal (e.g. post the code of conduct, etc)
diff --git a/github-management/org-owners-guide.md b/github-management/org-owners-guide.md
new file mode 100644
index 00000000..d0217f1d
--- /dev/null
+++ b/github-management/org-owners-guide.md
@@ -0,0 +1,96 @@
+# 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
+for CNCF compliance and for the guidelines of the community.
+
+## Organization Naming
+
+Kubernetes managed organizations should be in the form of `kubernetes-[thing]`.
+For example, [kubernetes-client](https://github.com/kubernetes-client) where the
+API clients are housed.
+
+Prior to creating an organization please contact the steering committee for
+direction and approval.
+
+Note: The CNCF, as part of the Linux Foundation, holds the trademark on the
+Kubernetes name. All GitHub organizations with Kubernetes in the name should be
+managed by the Kubernetes project or use a different name.
+
+## Transferring Outside Code Into A Kubernetes Organization
+
+Due to licensing and CLA issues, prior to transferring software into a Kubernetes
+managed organization there is some due diligence that needs to occur. Please
+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:
+
+- teams for each repo `foo`
+  - `foo-admins`: granted admin access to the `foo` repo
+  - `foo-maintainers`: granted write access to the `foo` repo
+  - `foo-reviewers`: granted read access to the `foo` repo; intended to be used as
+    a notification mechanism for interested/active contributors for the `foo` repo
+- a `bots` team
+  - should contain bots such as @k8s-ci-robot and @thelinuxfoundation that are
+    necessary for org and repo automation
+- an `owners` team
+  - should be populated by everyone who has `owner` privileges to the org
+  - gives users the opportunity to ping owners as a group rather than having to
+    search for individuals
+
+**NB**: Not all organizations in use today currently follow this team guidance.
+We are looking to coalesce existing teams towards this model, and use this model
+for all orgs going forward.  Notable discrepancies at the moment:
+
+- `foo-reviewers` teams are considered a historical subset of
+  `kubernetes-sig-foo-pr-reviews` teams and are intended mostly as a fallback
+  notification mechanism when requested reviewers are being unresponsive.  Ideally
+  OWNERS files can be used in lieu of these teams.
+- `admins-foo` and `maintainers-foo` teams as used by the kubernetes-incubator
+  org. This was a mistake that swapped the usual convention, and we would like
+  to rename the team
+
+## Repository Guidance
+
+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).
diff --git a/github-management/setting-up-cla-check.md b/github-management/setting-up-cla-check.md
new file mode 100644
index 00000000..bb344190
--- /dev/null
+++ b/github-management/setting-up-cla-check.md
@@ -0,0 +1,60 @@
+# Setting up the CNCF CLA check
+
+If you are trying to sign the CLA so your PR's can be merged, please 
+[read the CLA docs](https://git.k8s.io/community/CLA.md)
+
+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 on.
+
+## Setup the webhook
+
+1. Go to the settings for your organization or webhook, and choose Webhooks from the menu, then
+   "Add webhook"
+    - 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.
+    - Content Type: 'application/json'
+    - Secret: Please contact [@idvoretskyi](mailto:ihor@cncf.io), and [@caniszczyk](mailto:caniszczyk@linuxfoundation.org).
+    - Events: Let me select individual events
+      - Push: **unchecked**
+      - Pull request: checked
+      - Issue comment: checked
+      - Active: checked
+1. Add the [@thelinuxfoundation](https://github.com/thelinuxfoundation) GitHub user as an **Owner**
+   to your organization or repo to ensure the CLA status can be applied on PR's
+1. After you send an invite, contact the [Linux Foundation](mailto:helpdesk@rt.linuxfoundation.org); and cc [Chris Aniszczyk](mailto:caniszczyk@linuxfoundation.org), [Ihor Dvoretskyi](mailto:ihor@cncf.io), [Eric Searcy](mailto:eric@linuxfoundation.org) (to ensure that the invite gets accepted).
+1. Finally, open up a test PR to check that:
+    1. webhooks are delivered correctly, which can be monitored in the “settings” for your org
+    1. the PR gets the cla/linuxfoundation status
+
+## Branch protection
+
+It is recommended that the Linux Foundation CLA check be added as a strict requirement
+for any change to be accepted to the master branch.
+
+To do this manually:
+
+1. Go to the Settings for the repository, and choose Branches from the menu.
+1. Under Protected Branches, choose "master".
+1. Check "Protect this branch".
+1. Check "Require status checks to pass before merging", "Require branches to be up to date before merging", and the "cla/linuxfoundation" status check.
+
+Given the Kubernetes projects anticipates having "human reviewed" CLA acceptance, you may
+not do the last step, but it is still recommended to enable branch protection to require all
+changes to be done through pull requests, instead of direct pushing that will never kick off
+a CLA check.
+
+## Label automation
+
+The label automation is done using the [CLA plugin in prow](https://git.k8s.io/test-infra/prow/plugins/cla).
+In order to turn on the CLA labels on your repo, add it as appropriate within the
+[plugins.yaml](https://git.k8s.io/test-infra/prow/plugins.yaml), and add the cla plugin to it.
+
+You also need to add [@k8s-ci-robot](https://github.com/k8s-ci-robot) as one of the owners in
+the same org/repo, to ensure that it can add labels `cncf-cla: yes` and `cncf-cla: no` based
+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
+suffice.