word wrap github management subproject at 80-char width

doing these changes in a separate PR before doing content changes
in followup PR's
This commit is contained in:
Aaron Crickenberger 2018-10-08 17:03:22 -07:00
parent e1ff746c22
commit 93967792ce
3 changed files with 164 additions and 91 deletions

View File

@ -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/\<project-name\>.
* Must contain the topic for the sponsoring SIG - e.g. `k8s-sig-api-machinery`. (Added through the *Manage topics* link on the repo page.)
* Must 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 <Project Authors>"` 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 <Project Authors>"` if no CLA was in place prior to donation
## Core Repositories
Core repositories are considered core components of Kubernetes. They are utilities, tools, applications, or libraries that are expected to be present in every or nearly every Kubernetes cluster, such as components and tools included in official Kubernetes releases. Additionally, the kubernetes.io website, k8s.io machinery, and other project-wide infrastructure will remain in the kubernetes github organization.
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/<project-name>`
* Must adopt the Kubernetes Code of Conduct
* All code projects use the Apache Licence version 2.0. Documentation repositories must use the Creative Commons License version 4.0.
* 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. Well 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. Well 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 thats 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 thats
not in this proposal.
**My project is currently in core, but doesnt seem to fit these guidelines, whats going to happen?**
**My project is currently in core, but doesnt seem to fit these guidelines,
whats 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.
**Im 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 youd like, and make it an associated project.
Is this a small-group or personal project? If so, create a repository wherever
youd 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

View File

@ -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

View File

@ -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 youre 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 youre not
using merge automation. For repos with maintainers doing manual merges, GitHub
protected branches may suffice.