From 9ce2bdc3bb1a9e5b0acea5a4a2dbe8870041de28 Mon Sep 17 00:00:00 2001 From: Christoph Blecker Date: Wed, 20 Jun 2018 19:48:00 -0700 Subject: Move existing github related docs to dedicated folder --- github-management/kubernetes-repositories.md | 157 +++++++++++++++++++++++++++ github-management/org-owners-guide.md | 96 ++++++++++++++++ github-management/setting-up-cla-check.md | 60 ++++++++++ 3 files changed, 313 insertions(+) create mode 100644 github-management/kubernetes-repositories.md create mode 100644 github-management/org-owners-guide.md create mode 100644 github-management/setting-up-cla-check.md (limited to 'github-management') 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/\. + * 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 "` 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/` + * 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. -- cgit v1.2.3 From 5d635348ababd1ace7ec1cd4e92ce71b594dd9bd Mon Sep 17 00:00:00 2001 From: Christoph Blecker Date: Tue, 26 Jun 2018 12:52:25 -0700 Subject: Add README to github-management --- github-management/README.md | 69 +++++++++++++++++++++++++++++++ github-management/org-owners-guide.md | 36 +--------------- github-management/setting-up-cla-check.md | 4 +- 3 files changed, 72 insertions(+), 37 deletions(-) create mode 100644 github-management/README.md (limited to 'github-management') diff --git a/github-management/README.md b/github-management/README.md new file mode 100644 index 00000000..87f9640f --- /dev/null +++ b/github-management/README.md @@ -0,0 +1,69 @@ +# 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) + +## 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/github-management/org-owners-guide.md b/github-management/org-owners-guide.md index d0217f1d..7a4b6c6e 100644 --- a/github-management/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: diff --git a/github-management/setting-up-cla-check.md b/github-management/setting-up-cla-check.md index bb344190..d679b804 100644 --- a/github-management/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. -- cgit v1.2.3 From 402037e030d98fcf14c5b0d129664e220e96fb8c Mon Sep 17 00:00:00 2001 From: Christoph Blecker Date: Tue, 26 Jun 2018 11:57:45 -0700 Subject: Add GitHub Permissions doc --- github-management/README.md | 1 + github-management/permissions.md | 101 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 102 insertions(+) create mode 100644 github-management/permissions.md (limited to 'github-management') diff --git a/github-management/README.md b/github-management/README.md index 87f9640f..9284fe78 100644 --- a/github-management/README.md +++ b/github-management/README.md @@ -13,6 +13,7 @@ enforcement of these policies. - [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 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/ -- cgit v1.2.3 From a9ef298b3b879198b068cf94e251b9226d562bd0 Mon Sep 17 00:00:00 2001 From: Christoph Blecker Date: Wed, 20 Jun 2018 19:52:45 -0700 Subject: Add minor changes to repo guidelines --- github-management/kubernetes-repositories.md | 13 ++++++------- github-management/org-owners-guide.md | 2 +- 2 files changed, 7 insertions(+), 8 deletions(-) (limited to 'github-management') diff --git a/github-management/kubernetes-repositories.md b/github-management/kubernetes-repositories.md index 0651e3fb..7b1faf3b 100644 --- a/github-management/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/github-management/org-owners-guide.md b/github-management/org-owners-guide.md index 7a4b6c6e..ad7c8a7e 100644 --- a/github-management/org-owners-guide.md +++ b/github-management/org-owners-guide.md @@ -59,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) -- cgit v1.2.3 From 8adb7c849a02336ced34c8613008358ccc68a103 Mon Sep 17 00:00:00 2001 From: Christoph Blecker Date: Wed, 18 Jul 2018 15:06:08 -0700 Subject: Establish GitHub Management Subproject --- github-management/OWNERS | 7 +++++++ github-management/README.md | 4 ++++ github-management/subproject-responsibilites.md | 27 +++++++++++++++++++++++++ 3 files changed, 38 insertions(+) create mode 100644 github-management/OWNERS create mode 100644 github-management/subproject-responsibilites.md (limited to 'github-management') diff --git a/github-management/OWNERS b/github-management/OWNERS new file mode 100644 index 00000000..70807ad1 --- /dev/null +++ b/github-management/OWNERS @@ -0,0 +1,7 @@ +reviewers: + - cblecker +approvers: + - cblecker +labels: + - sig/contributor-experience + - area/github-management diff --git a/github-management/README.md b/github-management/README.md index 9284fe78..a15b7a66 100644 --- a/github-management/README.md +++ b/github-management/README.md @@ -9,6 +9,10 @@ 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. +These polices are overseen by the +[GitHub Management subproject](subproject-responsibilites.md) of the Contributor +Experience Special Interest Group. + ## Guides - [Organization Owners Guide](org-owners-guide.md) - [Repository Creation Guidelines](kubernetes-repositories.md) diff --git a/github-management/subproject-responsibilites.md b/github-management/subproject-responsibilites.md new file mode 100644 index 00000000..a3aa7fd1 --- /dev/null +++ b/github-management/subproject-responsibilites.md @@ -0,0 +1,27 @@ +# GitHub Management Subproject Responsibilities + +This subproject will be responsible for: +- Establishing policies, standards, and procedures for routine GitHub management + tasks, including but not limited to: org membership, org permissions, repo + creation/administration +- Establishing a policy around "Org Owner" permissions, and grant/limit these + privileges accordingly +- Establishing policies and best practices for bot accounts, service accounts, + webooks, and third-party integrations +- Maintaining documentation related to the above +- Establishing a "GitHub Administration team" that will oversee the execution of + GitHub management tasks (inviting new members to the org, creating repos, + executing moderation decisions, auditing permissions) +- Working with other sigs and interested parties in the project to execute + GitHub tasks where required + +This subproject will explicitly not be responsible for: +- Tooling and automation for GitHub (this falls under sig-testing, and the + sig-contributor-experience Contributor Workflow and Automation subproject) +- Determining policies around which repos can get created (this falls under + sig-architecture and the steering committee) +- Moderation policies and escalations on GitHub (this falls under the Moderation + subproject, the Code of Conduct committee, and the steering committee) +- Contributor workflow within Kubernetes repos, e.g. mandated use of labels + (this falls under the guise of the subproject responsible for the repo, and + the Contributor Workflow and Automation subproject) -- cgit v1.2.3 From c48e88b323a23f3ded16fabd32b02de99f6ffde1 Mon Sep 17 00:00:00 2001 From: Christoph Blecker Date: Mon, 30 Jul 2018 12:27:47 -0700 Subject: Form GitHub Administration Team --- github-management/OWNERS | 6 ++++++ github-management/README.md | 24 ++++++++++++++++++++++++ github-management/permissions.md | 4 +++- 3 files changed, 33 insertions(+), 1 deletion(-) (limited to 'github-management') diff --git a/github-management/OWNERS b/github-management/OWNERS index 70807ad1..cab8996b 100644 --- a/github-management/OWNERS +++ b/github-management/OWNERS @@ -1,7 +1,13 @@ reviewers: + - calebamiles - cblecker + - fejta + - grodrigues3 + - idvoretskyi + - spiffxp approvers: - cblecker + - grodrigues3 labels: - sig/contributor-experience - area/github-management diff --git a/github-management/README.md b/github-management/README.md index a15b7a66..73bb5eae 100644 --- a/github-management/README.md +++ b/github-management/README.md @@ -19,6 +19,30 @@ Experience Special Interest Group. - [Setting up the CNCF CLA Check](setting-up-cla-check.md) - [GitHub Permissions](permissions.md) +## GitHub Administration Team + +In order to manage the various organizations that the Kubernetes project owns, +we have a GitHub Administration team that is responsible for carrying out the +various tasks. + +This team (**[@kubernetes/owners](https://github.com/orgs/kubernetes/teams/owners)**) is as follows: +* Aaron Crickenberger (**[@spiffxp](https://github.com/spiffxp)**, US Pacific) +* Caleb Miles (**[@calebamiles](https://github.com/calebamiles)**, US Pacific) +* Christoph Blecker (**[@cblecker](https://github.com/cblecker)**, CA Pacific) +* Erick Fejta (**[@fejta](https://github.com/fejta)**, US Pacific) +* Garrett Rodrigues (**[@grodrigues3](https://github.com/grodrigues3)**, US Pacific) +* Ihor Dvoretskyi (**[@idvoretskyi](https://github.com/idvoretskyi)**, UA Eastern European) + +This team is responsible for holding Org Owner privileges over all the active +Kubernetes orgs, and will take action in accordance with our polices and +procedures. All members of this team are subject to the Kubernetes +[security embargo policy](https://git.k8s.io/sig-release/security-release-process-documentation/security-release-process.md#embargo-policy). + +Nominations to this team will come from the Contributor Experience SIG, and +require confirmation by the Steering Committee before taking effect. Time zones +and country of origin should be considered when selecting membership, to ensure +sufficient after North American business hours and holiday coverage. + ## Project Owned Organizations The following organizations are currently known to be part of the Kubernetes diff --git a/github-management/permissions.md b/github-management/permissions.md index 3ae03c70..ba036fee 100644 --- a/github-management/permissions.md +++ b/github-management/permissions.md @@ -36,7 +36,8 @@ There are certain actions that require org owner access: - Transfer repositories - Approve GitHub application integrations -**// TODO(cblecker):** Define specific roles that need this. +In the Kubernetes project, this role is held by the +[GitHub Administration Team]. ### Member @@ -93,6 +94,7 @@ member in the organization. [bot commands]: https://go.k8s.io/bot-commands [community membership]: /community-membership.md +[GitHub Administration Team]: /github-management/README.md#github-administration-team [org permissions]: https://help.github.com/articles/permission-levels-for-an-organization/ [OWNERS]: /contributors/guide/owners.md -- cgit v1.2.3 From 038d0d716bbfe0b8522922938c5a421e49db5b70 Mon Sep 17 00:00:00 2001 From: Aaron Crickenberger Date: Mon, 6 Aug 2018 11:16:34 -0700 Subject: Unindent headers by one level --- github-management/kubernetes-repositories.md | 30 ++++++++++++++-------------- 1 file changed, 15 insertions(+), 15 deletions(-) (limited to 'github-management') diff --git a/github-management/kubernetes-repositories.md b/github-management/kubernetes-repositories.md index 7b1faf3b..916fdd5f 100644 --- a/github-management/kubernetes-repositories.md +++ b/github-management/kubernetes-repositories.md @@ -1,35 +1,35 @@ -## Kubernetes Repository Guidelines +# 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 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 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 +### 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 +### 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 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 +### 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 +### Rules for new repositories * For now all repos will live in github.com/kubernetes-sigs/\. * Must contain the topic for the sponsoring SIG - e.g. `k8s-sig-api-machinery`. (Added through the *Manage topics* link on the repo page.) @@ -40,7 +40,7 @@ To provide a place for SIGs to collaborate on projects endorsed by and actively * 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 +### 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 @@ -55,14 +55,14 @@ In addition to the requirements for new repositories, donated repositories must * 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 "` if no CLA was in place prior to donation -### Core Repositories +## 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 +### 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 +### Rules * Must live under `github.com/kubernetes/` * Must adopt the Kubernetes Code of Conduct @@ -72,7 +72,7 @@ Create a broader base of repositories than the existing gh/kubernetes/kubernetes * 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 +## 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. @@ -85,7 +85,7 @@ wide processes, it ensures a rapid response to potential required fixes contributors and users receive quick feedback on their issues and contributions. -#### Grounds for removal +### 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: @@ -100,7 +100,7 @@ project and are generally not subject to removal, except under exceptional circumstances (e.g. a code of conduct violation). -#### Procedure for removal +### 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 @@ -111,7 +111,7 @@ use the [github archive feature](https://help.github.com/articles/archiving-a-gi The decision to archive a repository will be made by SIG architecture and announced on the Kubernetes dev mailing list and community meeting. -### FAQ +## FAQ *My project is currently in kubernetes-incubator, what is going to happen to it?* -- cgit v1.2.3 From c7b5ea1f79dc87818d7ec5130ece5067b142c0fd Mon Sep 17 00:00:00 2001 From: Aaron Crickenberger Date: Mon, 6 Aug 2018 11:34:00 -0700 Subject: github management: tweak repo removal language Added a new case I just ran into, and removed SIG Architecture from having to be involved in the decision to archive (I view consulting SIG Arch as part of the process for finding new active maintainers of the project, we could bake this into the language if it needs to be explicit) Formatting changes: - Trimmed whitespace in the FAQ - Unindented headers - FAQ questions are now bold rather than italic - Repo removal is a checklist to follow --- github-management/kubernetes-repositories.md | 56 +++++++++++++--------------- 1 file changed, 26 insertions(+), 30 deletions(-) (limited to 'github-management') diff --git a/github-management/kubernetes-repositories.md b/github-management/kubernetes-repositories.md index 916fdd5f..c1082a6a 100644 --- a/github-management/kubernetes-repositories.md +++ b/github-management/kubernetes-repositories.md @@ -86,71 +86,67 @@ 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. + 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. + * The contents have been folded into another actively maintained project. 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. +When a repository has been deemed eligible for removal, we take the following steps: -## FAQ + * Ownership of the repo is transferred to the [kubernetes-retired] GitHub organization + * The repo description is edited to start with the phrase "[EOL]" + * All open issues and PRs are closed + * All external collaborators are removed + * All webhooks, apps, integrations or services are removed + * GitHub Pages are disabled + * The repo is marked as archived using [GitHub's archive feature] + * The removal is announced on the kubernetes-dev mailing list and community meeting -*My project is currently in kubernetes-incubator, what is going to happen to it?* +This maintains the complete record of issues, PRs and other contributions, +leaves the repository read-only, and makes it clear that the repository +should be considered retired and unmaintained. -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. +## 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?* +**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?* +**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?* +**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?* +**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!* +**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) + +[GitHub's archive feature]: https://help.github.com/articles/archiving-a-github-repository/ +[kubernetes-retired]: https://github.com/kubernetes-retired -- cgit v1.2.3 From 22f00f26090af5f257b4959a5e069aec598c5137 Mon Sep 17 00:00:00 2001 From: Christoph Blecker Date: Tue, 7 Aug 2018 12:44:17 -0700 Subject: Add information on GAT SLOs --- github-management/org-owners-guide.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) (limited to 'github-management') diff --git a/github-management/org-owners-guide.md b/github-management/org-owners-guide.md index ad7c8a7e..0ac510d9 100644 --- a/github-management/org-owners-guide.md +++ b/github-management/org-owners-guide.md @@ -4,6 +4,26 @@ 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. +## SLOs + +The [GitHub Administration Team] will aim to handle requests in the following +time frames: +- Organization invites should be handled within 72 hours of all requirements for + membership being met (all +1s obtained). +- Repository creation or migration requests should be responded to within 72 + hours of the issue being opened. There may be information required or specific + requirements that take additional time, but once all requirements are met, the + repo should be created within 72 hours. +- Security or moderation requests should be handled ASAP, and coverage should be + provided in multiple time zones and countries. +- All other requests should be responded to within 72 hours of the issue being + opened. The time to resolve these requests will vary depending on the + specifics of the request. + +If a request is taking longer than the above time frames, or there is a need to +escalate an urgent request, please mention **[@kubernetes/owners]** on the +associated issue for assistance. + ## Organization Naming Kubernetes managed organizations should be in the form of `kubernetes-[thing]`. @@ -60,3 +80,7 @@ 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), and the [Repository Guidelines](kubernetes-repositories.md) + + +[GitHub Administration Team]: /github-management/README.md#github-administration-team +[@kubernetes/owners]: https://github.com/orgs/kubernetes/teams/owners -- cgit v1.2.3 From a62f3feac77f8f113f455c77618d8703a0634a08 Mon Sep 17 00:00:00 2001 From: Christoph Blecker Date: Tue, 7 Aug 2018 14:01:46 -0700 Subject: Add information on how to open a request with the GAT. --- github-management/README.md | 1 + github-management/opening-a-request.md | 33 +++++++++++++++++++++++++++++++++ 2 files changed, 34 insertions(+) create mode 100644 github-management/opening-a-request.md (limited to 'github-management') diff --git a/github-management/README.md b/github-management/README.md index 73bb5eae..043bb5da 100644 --- a/github-management/README.md +++ b/github-management/README.md @@ -14,6 +14,7 @@ These polices are overseen by the Experience Special Interest Group. ## Guides +- [Opening a request for assistance with GitHub](opening-a-request.md) - [Organization Owners Guide](org-owners-guide.md) - [Repository Creation Guidelines](kubernetes-repositories.md) - [Setting up the CNCF CLA Check](setting-up-cla-check.md) diff --git a/github-management/opening-a-request.md b/github-management/opening-a-request.md new file mode 100644 index 00000000..32f6acb3 --- /dev/null +++ b/github-management/opening-a-request.md @@ -0,0 +1,33 @@ +# Opening a issue for support with GitHub + +## GitHub issues + +If you need help with the following: +- Permissions issues +- Organization membership +- Third-party integrations +- Webhooks +- Repository creation/migration +- Repository archival +- Other repository and configuration issues + +Please open an issue against the [kubernetes/org] repository describing your +issue. If your request is urgent, please escalate to **[@kubernetes/owners]**. + +## Bot/Automation issues + +If you need help with the following: +- Bot configuration +- Automatic merging +- Label issues +- Automation feedback and feature requests + +Please open an issue against the [kubernetes/test-infra] repository describing +your issue. If your request is urgent, please escalate to the +[test-infra on-call] or reach out to `#testing-ops` on Slack. + + +[kubernetes/org]: https://github.com/kubernetes/org/issues +[@kubernetes/owners]: https://github.com/orgs/kubernetes/teams/owners +[kubernetes/test-infra]: https://github.com/kubernetes/test-infra/issues +[test-infra on-call]: https://go.k8s.io/oncall -- cgit v1.2.3 From 4c25d2a40f314f10cbfe44176dde4da8d96fe30a Mon Sep 17 00:00:00 2001 From: Christoph Blecker Date: Thu, 9 Aug 2018 15:33:21 -0700 Subject: Fix wording nit --- github-management/opening-a-request.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'github-management') diff --git a/github-management/opening-a-request.md b/github-management/opening-a-request.md index 32f6acb3..b0088647 100644 --- a/github-management/opening-a-request.md +++ b/github-management/opening-a-request.md @@ -19,7 +19,7 @@ issue. If your request is urgent, please escalate to **[@kubernetes/owners]**. If you need help with the following: - Bot configuration - Automatic merging -- Label issues +- Issue labelling - Automation feedback and feature requests Please open an issue against the [kubernetes/test-infra] repository describing -- cgit v1.2.3 From 4b9ee3107502eaa3391b7ee66b1a16fb63c86395 Mon Sep 17 00:00:00 2001 From: Mike Brown Date: Tue, 4 Sep 2018 10:09:41 -0500 Subject: include projects in wording Signed-off-by: Mike Brown --- github-management/kubernetes-repositories.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'github-management') diff --git a/github-management/kubernetes-repositories.md b/github-management/kubernetes-repositories.md index c1082a6a..27920f39 100644 --- a/github-management/kubernetes-repositories.md +++ b/github-management/kubernetes-repositories.md @@ -23,7 +23,7 @@ To facilitate contributions and collaboration from the broader Kubernetes commun ## 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. +SIG repositories serve as temporary homes for SIG-sponsored experimental projects or prototypes of new core functionality, or as permanent homes for SIG-specific projects and tools. ### Goals -- cgit v1.2.3 From 68d1ee6efd06773661eb14dc5ce5f3752e0aaf81 Mon Sep 17 00:00:00 2001 From: Christoph Blecker Date: Wed, 19 Sep 2018 12:30:13 -0700 Subject: Add TOC to kubernetes-repositories.md --- github-management/kubernetes-repositories.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) (limited to 'github-management') diff --git a/github-management/kubernetes-repositories.md b/github-management/kubernetes-repositories.md index 27920f39..3c5b48ec 100644 --- a/github-management/kubernetes-repositories.md +++ b/github-management/kubernetes-repositories.md @@ -5,6 +5,21 @@ 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) + * [Goals](#goals) + * [Rules](#rules) +- [SIG repositories](#sig-repositories) + * [Goals](#goals-1) + * [Rules for new repositories](#rules-for-new-repositories) + * [Rules for donated repositories](#rules-for-donated-repositories) +- [Core Repositories](#core-repositories) + * [Goals](#goals-2) + * [Rules](#rules-1) +- [Removing Repositories](#removing-repositories) + * [Grounds for removal](#grounds-for-removal) + * [Procedure for removal](#procedure-for-removal) +- [FAQ](#faq) + ## 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. -- cgit v1.2.3 From 851e8e8367436021c0fdce54df37203560cce682 Mon Sep 17 00:00:00 2001 From: Christoph Blecker Date: Wed, 19 Sep 2018 12:30:33 -0700 Subject: Add line to kubernetes-repositories.md describing how to open a request --- github-management/kubernetes-repositories.md | 2 ++ 1 file changed, 2 insertions(+) (limited to 'github-management') diff --git a/github-management/kubernetes-repositories.md b/github-management/kubernetes-repositories.md index 3c5b48ec..beccb0e7 100644 --- a/github-management/kubernetes-repositories.md +++ b/github-management/kubernetes-repositories.md @@ -5,6 +5,8 @@ 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. +Requests for creating, transferring, modifying, or archiving repositories can be made by [opening a request](https://github.com/kubernetes/org/issues/new/choose) against the kubernetes/org repo. + - [Associated Repositories](#associated-repositories) * [Goals](#goals) * [Rules](#rules) -- cgit v1.2.3 From 841f54aa36e95f44039d205fb7c24d9353957f73 Mon Sep 17 00:00:00 2001 From: Christoph Blecker Date: Mon, 1 Oct 2018 11:37:13 -0700 Subject: Add new membership procedure doc --- github-management/new-membership-procedure.md | 103 ++++++++++++++++++++++++++ 1 file changed, 103 insertions(+) create mode 100644 github-management/new-membership-procedure.md (limited to 'github-management') diff --git a/github-management/new-membership-procedure.md b/github-management/new-membership-procedure.md new file mode 100644 index 00000000..f292bfc7 --- /dev/null +++ b/github-management/new-membership-procedure.md @@ -0,0 +1,103 @@ +# Adding a new member to a Kubernetes GitHub Org + +This procedure outlines the steps to add someone to a Kubernetes GitHub +organization. These directions are based off of the [community membership] +guidelines. If there is a discrepancy as to the exact membership requirements, +the [community membership] guidelines take precedence. + +## Membership Requirements + +All members of the Kubernetes GitHub org are required to do the following: + +- Have 2FA enabled on their GitHub account + + This is enforced by GitHub. The contributor will not be able to accept the org + invitation without it, and they will be removed from the org automatically in + the event they disable it. + +- Join the [k-dev] mailing list + + We don't explicitly check this, but we require the contributor to check the + box saying that they have joined. + +- List their active contributions + + This is left purposefully vague. We want to record what those contributions + are, but we leave it up to the sponsors to determine if they are at a bar that + warrants membership. We want to make it easy for those who are actively + contributing to join, but this bar should be higher than, for example, a few + spelling corrections. + +- List the active subprojects they are involved in + + In the same vein as the above, we leave this vague, and as guidance for the + sponsors. The sponsors should also be active in these same subprojects. + +## Sponsor Requirements + +One of the most critical pieces in the process is validating the sponsors meet +the requirements to sponsor a new member. With the size of the Kubernetes +project, those involved with processing new memberships do not have the +visibility to determine if each prospective member's contributions meet the +standard needed to become a member. We rely on sponsors to vouch for the work of +the prospective new member, and to validate the work they are doing. + +We do however, have to validate that the sponsor's credentials meet the standard +required to be eligible to sponsor a new member. These requirements are: + +- Sponsors must be a member of the org they are attempting to sponsor for. + + For example, if the membership being requested is for kubernetes-incubator, + then the sponsor should be a member of either that org, or main Kubernetes + org (as members of the main org have implicit membership in other orgs). + +- Sponsors must be a reviewer or approver in at least one OWNERS file in any + Kubernetes GitHub org. + +- Sponsors must be from multiple member companies to demonstrate integration + across community + + A single sponsor may be from the same company as the prospective member, but + no more than one sponsor can be from the same company. If both sponsors on an + application are from the same company, please request that the applicant + solicit an additional sponsor from a different company. + +- Sponsors must have close interactions with the prospective member + + Sponsors need to be familiar enough with the prospective member's + contributions to be able to properly vouch for them. This is to ensure + integrity in the membership process, and a "web of trust" for the privileges + we afford members. + +If there are questions with regard to a sponsor's qualifications, please attempt +to seek clarification or a second opinion before moving forward with processing +the membership. + +## Processing the request + +Once all the requirements have been validated, we can move forward with +processing the membership. + +1. Open a PR against the [kubernetes/org] config, adding the potential member's +GitHub username to the members list. Note, that the list is alpha sorted, but +case insensitive. + +1. For clarity, please use one commit per username added (although you may add +that user to multiple orgs in the same commit). + +1. In the PR body (and not the commit message), add `fixes #1234, fixes #1234` +with the issue numbers of the membership request issues that this PR is +resolving. One PR can be used to resolve multiple membership requests. + +1. Add a note to the original membership request stating that a membership +invite will be sent out once the PR has merged. + +1. Wait for a member of the GitHub administration team to approve the PR for +merge. + + + + +[community membership]: /community-membership.md +[k-dev]: https://groups.google.com/forum/#!forum/kubernetes-dev +[kubernetes/org]: https://git.k8s.io/org/ -- cgit v1.2.3 From 93967792ceea3338da723595d7d17603aab8ea4e Mon Sep 17 00:00:00 2001 From: Aaron Crickenberger Date: Mon, 8 Oct 2018 17:03:22 -0700 Subject: word wrap github management subproject at 80-char width doing these changes in a separate PR before doing content changes in followup PR's --- github-management/kubernetes-repositories.md | 150 ++++++++++++++++++--------- github-management/org-owners-guide.md | 27 ++--- github-management/setting-up-cla-check.md | 78 ++++++++------ 3 files changed, 164 insertions(+), 91 deletions(-) (limited to 'github-management') diff --git a/github-management/kubernetes-repositories.md b/github-management/kubernetes-repositories.md index beccb0e7..6e3b4905 100644 --- a/github-management/kubernetes-repositories.md +++ b/github-management/kubernetes-repositories.md @@ -1,11 +1,16 @@ # 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. +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. -Requests for creating, transferring, modifying, or archiving repositories can be made by [opening a request](https://github.com/kubernetes/org/issues/new/choose) against the kubernetes/org repo. +Requests for creating, transferring, modifying, or archiving repositories can be +made by [opening a request](https://github.com/kubernetes/org/issues/new/choose) +against the kubernetes/org repo. - [Associated Repositories](#associated-repositories) * [Goals](#goals) @@ -24,38 +29,55 @@ Requests for creating, transferring, modifying, or archiving repositories can be ## 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. +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. +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. + * 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 projects and tools. +SIG repositories serve as temporary homes for SIG-sponsored experimental +projects or prototypes of new core functionality, or as permanent homes for +SIG-specific projects and 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) +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/\. - * 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 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. + * 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) + * 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 @@ -63,44 +85,57 @@ 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: +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 "` if no CLA was in place prior to donation + * 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 "` 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. +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. +### 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/` * 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. + * 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 + * 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. +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. +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 @@ -120,50 +155,69 @@ circumstances (e.g. a code of conduct violation). ### Procedure for removal -When a repository has been deemed eligible for removal, we take the following steps: +When a repository has been deemed eligible for removal, we take the following +steps: - * Ownership of the repo is transferred to the [kubernetes-retired] GitHub organization + * Ownership of the repo is transferred to the [kubernetes-retired] GitHub + organization * The repo description is edited to start with the phrase "[EOL]" * All open issues and PRs are closed * All external collaborators are removed * All webhooks, apps, integrations or services are removed * GitHub Pages are disabled * The repo is marked as archived using [GitHub's archive feature] - * The removal is announced on the kubernetes-dev mailing list and community meeting + * The removal is announced on the kubernetes-dev mailing list and community + meeting This maintains the complete record of issues, PRs and other contributions, -leaves the repository read-only, and makes it clear that the repository -should be considered retired and unmaintained. +leaves the repository read-only, and makes it clear that the repository should +be considered retired and unmaintained. ## FAQ -**My project is currently in kubernetes-incubator, what is going to happen to it?** +**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. +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. +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. +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?** +**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. +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 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. +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. +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!** +**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) +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) -[GitHub's archive feature]: https://help.github.com/articles/archiving-a-github-repository/ +[GitHub's archive feature]: +https://help.github.com/articles/archiving-a-github-repository/ [kubernetes-retired]: https://github.com/kubernetes-retired diff --git a/github-management/org-owners-guide.md b/github-management/org-owners-guide.md index 0ac510d9..c626d5c4 100644 --- a/github-management/org-owners-guide.md +++ b/github-management/org-owners-guide.md @@ -39,9 +39,9 @@ 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. +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. @@ -53,8 +53,9 @@ 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 + - `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 @@ -69,18 +70,20 @@ 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. + 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), and the [Repository Guidelines](kubernetes-repositories.md) +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), and the +[Repository Guidelines](kubernetes-repositories.md) - -[GitHub Administration Team]: /github-management/README.md#github-administration-team +[GitHub Administration Team]: +/github-management/README.md#github-administration-team [@kubernetes/owners]: https://github.com/orgs/kubernetes/teams/owners diff --git a/github-management/setting-up-cla-check.md b/github-management/setting-up-cla-check.md index d679b804..089b8b31 100644 --- a/github-management/setting-up-cla-check.md +++ b/github-management/setting-up-cla-check.md @@ -1,60 +1,76 @@ # 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 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. +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. +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). + - 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. 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. 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. +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. +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. +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. +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. +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. +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. -- cgit v1.2.3 From 2b4aa88e44f686846ce85e9c67cf9737ebbfe803 Mon Sep 17 00:00:00 2001 From: Christoph Blecker Date: Fri, 9 Nov 2018 15:35:42 -0800 Subject: Add info on NMC --- github-management/README.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) (limited to 'github-management') diff --git a/github-management/README.md b/github-management/README.md index 043bb5da..76d206f0 100644 --- a/github-management/README.md +++ b/github-management/README.md @@ -44,6 +44,19 @@ require confirmation by the Steering Committee before taking effect. Time zones and country of origin should be considered when selecting membership, to ensure sufficient after North American business hours and holiday coverage. +### Other roles + +#### New Membership Coordinator + +New Membership Coordinators help serve as a friendly face to newer, prospective +community members, guiding them through the +[process](new-membership-procedure.md) to request membership to a Kubernetes +GitHub organization. + +Our current coordinators are: +* Bob Killen (**[@mrbobbytables](https://github.com/mrbobbytables)**, US Eastern) +* Stephen Augustus (**[@justaugustus](https://github.com/justaugustus)**, US Eastern) + ## Project Owned Organizations The following organizations are currently known to be part of the Kubernetes -- cgit v1.2.3 From 249a50eb5ec4552b6ff46c5b4c8e4615b945e9d6 Mon Sep 17 00:00:00 2001 From: ramnar Date: Wed, 28 Nov 2018 01:37:08 +0530 Subject: Broken Links fix for 2696 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit FILE: ./sig-cloud-provider/CHARTER.md [✖] https://github.com/kubernetes/community/blob/master/keps/0002-controller-manager.md → Status: 404 [✖] https://github.com/kubernetes/community/blob/master/keps/0002-controller-manager.md#repository-requirements → Status: 404 FILE: ./github-management/setting-up-cla-check.md [✖] https://identity.linuxfoundation.org/lfcla/github/postreceive?group=284&comment=no&target=https://identity.linuxfoundation.org/projects/cncf → Status: 404 FILE: ./sig-scalability/blogs/k8s-services-scalability-issues.md [✖] https://cilium.io/blog/2018/04/17/why-is-the-kernel-community-replacing-iptables) → Status: 404 FILE: ./sig-scalability/goals.md [✖] provider-configs.md → Status: 400 Error: ENOENT: no such file or directory, access '/home/jorge/src/kubernetes/community/sig-scalability/provider-configs.md' --- github-management/setting-up-cla-check.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'github-management') diff --git a/github-management/setting-up-cla-check.md b/github-management/setting-up-cla-check.md index 089b8b31..be1ae381 100644 --- a/github-management/setting-up-cla-check.md +++ b/github-management/setting-up-cla-check.md @@ -11,7 +11,7 @@ setup the Linux Foundation CNCF CLA check for your repositories, please read on. 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 + `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 -- cgit v1.2.3