kubernetes
/
website
mirror of https://github.com/kubernetes/website.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Rebuild the community docs (#7498) 

* rebuild and update community imported docs

* redundant page titles

* Redundant page title removed
This commit is contained in:
grodrigues3 2018-02-26 09:14:43 -08:00 committed by k8s-ci-robot
parent 1458363f5a
commit 7d85f99953
4 changed files with 186 additions and 223 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
docs/imported/community/devel.md
View File

@ -15,7 +15,7 @@ Guide](http://kubernetes.io/docs/admin/).
* **GitHub Issues** ([issues.md](https://github.com/kubernetes/community/tree/master/contributors/devel/issues.md)): How incoming issues are triaged.
* **Pull Request Process** ([pull-requests.md](https://github.com/kubernetes/community/tree/master/contributors/devel/pull-requests.md)): When and why pull requests are closed.
* **Pull Request Process** ([/contributors/guide/pull-requests.md](https://github.com/kubernetes/community/tree/master/contributors/guide/pull-requests.md)): When and why pull requests are closed.
* **Getting Recent Builds** ([getting-builds.md](https://github.com/kubernetes/community/tree/master/contributors/devel/getting-builds.md)): How to get recent builds including the latest builds that pass CI.
@ -39,7 +39,7 @@ Guide](http://kubernetes.io/docs/admin/).
([instrumentation.md](https://github.com/kubernetes/community/tree/master/contributors/devel/instrumentation.md)): How to add a new metrics to the
Kubernetes code base.
* **Coding Conventions** ([coding-conventions.md](https://github.com/kubernetes/community/tree/master/contributors/devel/coding-conventions.md)):
* **Coding Conventions** ([coding-conventions.md](https://github.com/kubernetes/community/tree/master/contributors/devel/../guide/coding-conventions.md)):
Coding style advice for contributors.
* **Document Conventions** ([how-to-doc.md](https://github.com/kubernetes/community/tree/master/contributors/devel/how-to-doc.md))
@ -78,4 +78,3 @@ Guide](http://kubernetes.io/docs/admin/).
## Building releases
See the [kubernetes/release](https://github.com/kubernetes/release) repository for details on creating releases and related tools and helper scripts.
ed tools and helper scripts.

123
docs/imported/community/guide.md
View File

@ -1,29 +1,16 @@
---
title: Kubernetes Contributor Guide
owner: sig-contributor-experience
notitle: true
---
**OWNER:**
sig-contributor-experience
# Kubernetes Contributor Guide
## Disclaimer
Hello! This is the starting point for our brand new contributor guide, currently underway as per [issue#6102](https://github.com/kubernetes/website/issues/6102) and in need of help. Please be patient, or fix a section below that needs improvement, and submit a pull request!
Many of the links below should lead to relevant documents scattered across the community repository. Often, the linked instructions need to be updated or cleaned up.
Hello! This is the starting point for our brand new contributor guide, currently underway as per [issue#6102](https://github.com/kubernetes/website/issues/6102) and is in need of help.
Please be patient, or fix a section below that needs improvement, and submit a pull request! Feel free to browse the [open issues](https://github.com/kubernetes/community/issues?q=is%3Aissue+is%3Aopen+label%3Aarea%2Fcontributor-guide) and file new ones, all feedback welcome!
* If you do so, please move the relevant file from its previous location to the community/contributors/guide folder, and delete its previous location.
* Our goal is that all contributor guide specific files live in this folder.
Please find _Improvements needed_ sections below and help us out.
For example:
_Improvements needed_
* kubernetes/community/CONTRIBUTING.md -> Needs a rewrite
* kubernetes/community/README.md -> Needs a rewrite
* Individual SIG contributing documents -> add a link to this guide
# Welcome
@ -31,10 +18,10 @@ Welcome to Kubernetes! This document is the single source of truth for how to co
- [Before you get started](#before-you-get-started)
- [Sign the CLA](#sign-the-cla)
- [Code of Conduct](#code-of-conduct)
- [Setting up your development
environment](#setting-up-your-development-environment)
- [Community Expectations](#community-expectations)
- [Code of Conduct](#code-of-conduct)
- [Community Expectations and Roles](#community-expectations-and-roles)
- [Thanks](#thanks)
- [Your First Contribution](#your-first-contribution)
- [Find something to work on](#find-something-to-work-on)
@ -51,9 +38,9 @@ Welcome to Kubernetes! This document is the single source of truth for how to co
- [Documentation](#documentation)
- [Issues Management or Triage](#issues-management-or-triage)
- [Community](#community)
- [Communication](#communication-1)
- [Events](#events)
- [Meetups](#meetups)
- [KubeCon](#kubecon)
- [Mentorship](#mentorship)
# Before you get started
@ -62,36 +49,26 @@ Welcome to Kubernetes! This document is the single source of truth for how to co
Before you can contribute, you will need to sign the [Contributor License Agreement](https://github.com/kubernetes/community/tree/master/CLA.md).
## Code of Conduct
Please make sure to read and observe our [Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md).
## Setting up your development environment
If you haven’t set up your environment, please find resources [here](https://github.com/kubernetes/community/tree/master/contributors/devel). These resources are not well organized currently; please have patience as we are working on it.
If you haven’t set up your environment, please find resources [here](https://github.com/kubernetes/community/tree/master/contributors/devel).
_Improvements needed_
* A new developer guide will be created and linked to in this section.
* RyanJ from Red Hat is working on this
## Community Expectations
## Community Expectations and Roles
Kubernetes is a community project. Consequently, it is wholly dependent on its community to provide a productive, friendly and collaborative environment.
The first and foremost goal of the Kubernetes community to develop orchestration technology that radically simplifies the process of creating reliable distributed systems. However a second, equally important goal is the creation of a community that fosters easy, agile development of such orchestration systems.
We therefore describe the expectations for members of the Kubernetes community. This document is intended to be a living one that evolves as the community evolves via the same pull request and code review process that shapes the rest of the project. It currently covers the expectations of conduct that govern all members of the community as well as the expectations around code review that govern all active contributors to Kubernetes.
### Code of Conduct
Please make sure to read and observe our [Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md)
### Thanks
Many thanks in advance to everyone who contributes their time and effort to making Kubernetes both a successful system as well as a successful community. The strength of our software shines in the strengths of each individual community member. Thanks!
- Read and review the [Community Expectations](https://github.com/kubernetes/community/tree/master/contributors/guide/community-expectations.md) for an understand of code and review expectations.
- See [Community Membership](https://github.com/kubernetes/community/tree/master/community-membership.md) for a list the various responsibilities of contributor roles. You are encouraged to move up this contributor ladder as you gain experience.
# Your First Contribution
Have you ever wanted to contribute to the coolest cloud technology? We will help you understand the organization of the Kubernetes project and direct you to the best places to get started. You'll be able to pick up issues, write code to fix them, and get your work reviewed and merged.
Please be aware that due to the large number of issues our triage team deals with, we cannot offer technical support in GitHub issues. If you have questions about the development process, feel free to jump into our [Slack Channel](http://slack.k8s.io/) or join our [mailing list](https://groups.google.com/forum/#!forum/kubernetes-dev). You can also ask questions on [ServerFault](https://serverfault.com/questions/tagged/kubernetes) or [Stack Overflow](https://stackoverflow.com/questions/tagged/kubernetes). The Kubernetes team scans Stack Overflow on a regular basis, and will try to ensure your questions don't go unanswered.
Please be aware that due to the large number of issues our triage team deals with, we cannot offer technical support in GitHub issues. If you have questions about the development process, feel free to jump into our [Slack Channel](http://slack.k8s.io/) or join our [mailing list](https://groups.google.com/forum/#!forum/kubernetes-dev). You can also ask questions on [ServerFault](https://serverfault.com/questions/tagged/kubernetes) or [Stack Overflow](https://stackoverflow.com/questions/tagged/kubernetes). The Kubernetes team scans Stack Overflow on a regular basis and will try to ensure your questions don't go unanswered.
## Find something to work on
@ -109,7 +86,8 @@ Another good strategy is to find a documentation improvement, such as a missing/
#### Sig structure
You may have noticed that some repositories in the Kubernetes Organization are owned by Special Interest Groups, or SIGs. We organize the Kubernetes community into SIGs in order to improve our workflow and more easily manage what is a very large community project. The developers within each SIG have autonomy and ownership over that SIG's part of Kubernetes.
SIGs also have their own CONTRIBUTING.md files, which may contain extra information or guidelines in addition to these general ones. These are located in the SIG specific community documentation directories, for example: sig-docs' is in the kubernetes/community repo's [/sig-docs/CONTRIBUTING.md](https://github.com/kubernetes/community/tree/master/sig-docs/CONTRIBUTING.md) file and similarly for other SIGs.
Some SIGs also have their own `CONTRIBUTING.md` files, which may contain extra information or guidelines in addition to these general ones. These are located in the SIG-specific community directories. For example: the contributor's guide for SIG CLI is located in the *kubernetes/community* repo, as [`/sig-cli/CONTRIBUTING.md`](https://github.com/kubernetes/community/tree/master/sig-cli/CONTRIBUTING.md).
Like everything else in Kubernetes, a SIG is an open, community, effort. Anybody is welcome to jump into a SIG and begin fixing issues, critiquing design proposals and reviewing code. SIGs have regular [video meetings](https://kubernetes.io/community/) which everyone is welcome to. Each SIG has a kubernetes slack channel that you can join as well.
@ -119,23 +97,23 @@ show up to one of the [bi-weekly meetings](https://docs.google.com/document/d/1q
#### Find a SIG that is related to your contribution
Finding the appropriate SIG for your contribution will help you ask questions in the correct place and give your contribution higher visibility and a faster community response.
Finding the appropriate SIG for your contribution and adding a SIG label will help you ask questions in the correct place and give your contribution higher visibility and a faster community response.
For Pull Requests, the automatically assigned reviewer will add a SIG label if you haven't done so. See [Open A Pull Request](#open-a-pull-request) below.
For Issues we are still working on a more automated workflow. Since SIGs do not directly map onto Kubernetes subrepositories, it may be difficult to find which SIG your contribution belongs in. Here is the [list of SIGs](https://github.com/kubernetes/community/tree/master/sig-list.md). Determine which is most likely related to your contribution.
For Issues, we are still working on a more automated workflow. Since SIGs do not directly map onto Kubernetes subrepositories, it may be difficult to find which SIG your contribution belongs in. Here is the [list of SIGs](https://github.com/kubernetes/community/tree/master/sig-list.md). Determine which is most likely related to your contribution.
*Example:* if you are filing a cni issue, you should choose SIG-networking.
*Example:* if you are filing a cni issue, you should choose the [Network SIG](http://git.k8s.io/community/sig-network). Add the SIG label in a comment like so:
```
/sig network
```
Follow the link in the SIG name column to reach each SIGs README. Most SIGs will have a set of GitHub Teams with tags that can be mentioned in a comment on issues and pull requests for higher visibility. If you are not sure about the correct SIG for an issue, you can try SIG-contributor-experience [here](https://github.com/kubernetes/community/tree/master/sig-contributor-experience#github-teams), or [ask in Slack](http://slack.k8s.io/).
_Improvements needed_
* Open pull requests with all applicable SIGs to not have duplicate information in their CONTRIBUTING.md and instead link here. Keep it light, keep it clean, have only one source of truth.
### File an Issue
Not ready to contribute code, but see something that needs work? While the community encourages everyone to contribute code, it is also appreciated when someone reports an issue (aka problem). Issues should be filed under the appropriate Kubernetes subrepository.
Check the [issue triage guide](https://github.com/kubernetes/community/tree/master/contributors/guide/./issue-triage.md) for more information.
*Example:* a documentation issue should be opened to [kubernetes/website](https://github.com/kubernetes/website/issues).
@ -143,19 +121,21 @@ Make sure to adhere to the prompted submission guidelines while opening an issue
# Contributing
(From:[here](https://github.com/kubernetes/community/tree/master/contributors/devel/collab.md))
Kubernetes is open source, but many of the people working on it do so as their day job. In order to avoid forcing people to be "at work" effectively 24/7, we want to establish some semi-formal protocols around development. Hopefully these rules make things go more smoothly. If you find that this is not the case, please complain loudly.
Kubernetes is open source, but many of the people working on it do so as their day job. In order to avoid forcing people to be "at work" effectively 24/7, we want to establish some semi-formal protocols around development. Hopefully, these rules make things go more smoothly. If you find that this is not the case, please complain loudly.
As a potential contributor, your changes and ideas are welcome at any hour of the day or night, weekdays, weekends, and holidays. Please do not ever hesitate to ask a question or send a pull request.
Our community guiding principles on how to create great code as a big group are found [here](https://github.com/kubernetes/community/tree/master/contributors/devel/collab.md). Beginner focused information can be found below in [Open a Pull Request](#open-a-pull-request) and [Code Review](#code-review).
Our community guiding principles on how to create great code as a big group are found [here](https://github.com/kubernetes/community/tree/master/contributors/devel/collab.md).
Beginner focused information can be found below in [Open a Pull Request](#open-a-pull-request) and [Code Review](#code-review).
For quick reference on contributor resources, we have a handy [contributor cheatsheet](https://github.com/kubernetes/community/tree/master/contributors/guide/./contributor-cheatsheet.md)
### Communication
It is best to contact your [SIG](#learn-about-sigs) for issues related to the SIG's topic. Your SIG will be able to help you much more quickly than a general question would.
For questions and troubleshooting, please feel free to use any of the methods of communication listed [here](https://github.com/kubernetes/community/tree/master/communication.md). The [kubernetes website](https://kubernetes.io/docs/tasks/debug-application-cluster/troubleshooting/) also lists this information.
For general questions and troubleshooting, use the [kubernetes standard lines of communication](https://github.com/kubernetes/community/tree/master/communication.md) and work through the [kubernetes troubleshooting guide](https://kubernetes.io/docs/tasks/debug-application-cluster/troubleshooting/).
## GitHub workflow
@ -163,7 +143,9 @@ To check out code to work on, please refer to [this guide](https://github.com/ku
## Open a Pull Request
Pull requests are often called simply "PR". Kubernetes generally follows the standard [github pull request](https://help.github.com/articles/about-pull-requests/) process, but there is a layer of additional kubernetes specific (and sometimes SIG specific) differences.
Pull requests are often called simply "PR". Kubernetes generally follows the standard [github pull request](https://help.github.com/articles/about-pull-requests/) process, but there is a layer of additional kubernetes specific (and sometimes SIG specific) differences:
- [Kubernetes-specific github workflow](https://github.com/kubernetes/community/tree/master/contributors/guide/pull-requests.md#the-testing-and-merge-workflow).
The first difference you'll see is that a bot will begin applying structured labels to your PR.
@ -174,20 +156,20 @@ Common new contributor PR issues are:
* not having correctly signed the CLA ahead of your first PR (see [Sign the CLA](#sign-the-cla) section)
* finding the right SIG or reviewer(s) for the PR (see [Code Review](#code-review) section) and following any SIG specific contributing guidelines
* dealing with test cases which fail on your PR, unrelated to the changes you introduce (see [Test Flakes](http://velodrome.k8s.io/dashboard/db/bigquery-metrics?orgId=1))
The pull request workflow is described in detail [here](https://github.com/kubernetes/community/tree/master/contributors/devel/pull-requests.md#the-testing-and-merge-workflow).
* Not following [scalability good practices](https://github.com/kubernetes/community/tree/master/contributors/guide/scalability-good-practices.md)
## Code Review
For a brief description of the importance of code review, please read [On Code Review](https://github.com/kubernetes/community/tree/master/contributors/devel/community-expectations.md#code-review). There are two aspects of code review: giving and receiving.
For a brief description of the importance of code review, please read [On Code Review](https://github.com/kubernetes/community/tree/master/contributors/guide/community-expectations.md#code-review). There are two aspects of code review: giving and receiving.
To make it easier for your PR to receive reviews, consider the reviewers will need you to:
* follow the project [coding conventions](https://github.com/kubernetes/community/tree/master/contributors/guide/coding-conventions.md)
* write [good commit messages](https://chris.beams.io/posts/git-commit/)
* break large changes into a logical series of smaller patches which individually make easily understandable changes, and in aggregate solve a broader issue
* label PRs with appropriate SIGs and reviewers: to do this read the messages the bot sends you to guide you through the PR process
Reviewers, the people giving review, are highly encouraged to revisit the [Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md) and must go above and beyond to promote a collaborative, respectful Kubernetes community. When reviewing PRs from others [The Gentle Art of Patch Review](http://sage.thesharps.us/2014/09/01/the-gentle-art-of-patch-review/) suggests an iterative series of focuses which is designed to lead new contributors to positive collaboration without inundating them initially with nuances:
Reviewers, the people giving the review, are highly encouraged to revisit the [Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md) and must go above and beyond to promote a collaborative, respectful Kubernetes community. When reviewing PRs from others [The Gentle Art of Patch Review](http://sage.thesharps.us/2014/09/01/the-gentle-art-of-patch-review/) suggests an iterative series of focuses which is designed to lead new contributors to positive collaboration without inundating them initially with nuances:
* Is the idea behind the contribution sound?
* Is the contribution architected correctly?
@ -201,7 +183,7 @@ The main testing overview document is [here](https://github.com/kubernetes/commu
There are three types of test in kubernetes. The location of the test code varies with type, as does the specifics of the environment needed to successfully run the test:
* Unit: These confirm that a particular function behaves as intended. Golang includes native ability for unit testing via the [testing](https://golang.org/pkg/testing/) package. Unit test source code can be found adjacent to the corresponding source code within a given package. For example: functions defined in [kubernetes/cmd/kubeadm/app/util/version.go](https://git.k8s.io/kubernetes/cmd/kubeadm/app/util/version.go) will have unit tests in [kubernetes/cmd/kubeadm/app/util/version_test.go](https://git.k8s.io/kubernetes/cmd/kubeadm/app/util/version_test.go). These are easily run locally be any developer on any OS.
* Unit: These confirm that a particular function behaves as intended. Golang includes a native ability for unit testing via the [testing](https://golang.org/pkg/testing/) package. Unit test source code can be found adjacent to the corresponding source code within a given package. For example: functions defined in [kubernetes/cmd/kubeadm/app/util/version.go](https://git.k8s.io/kubernetes/cmd/kubeadm/app/util/version.go) will have unit tests in [kubernetes/cmd/kubeadm/app/util/version_test.go](https://git.k8s.io/kubernetes/cmd/kubeadm/app/util/version_test.go). These are easily run locally by any developer on any OS.
* Integration: These tests cover interactions of package components or interactions between kubernetes components and some other non-kubernetes system resource (eg: etcd). An example would be testing whether a piece of code can correctly store data to or retrieve data from etcd. Integration tests are stored in [kubernetes/test/integration/](https://git.k8s.io/kubernetes/test/integration). Running these can require the developer set up additional functionality on their development system.
* End-to-end ("e2e"): These are broad tests of overall kubernetes system behavior and coherence. These are more complicated as they require a functional kubernetes cluster built from the sources to be tested. A separate document [here](https://github.com/kubernetes/community/tree/master/contributors/devel/e2e-tests.md) details e2e testing and test cases themselves can be found in [kubernetes/test/e2e/](https://git.k8s.io/kubernetes/test/e2e).
@ -211,13 +193,12 @@ sig-testing is responsible for that official infrastructure and CI. The associa
## Security
_Improvements needed_
* Please help write this section.
## Documentation
_Improvements needed_
* Please help write this section.
- [Contributing to Documentation](https://kubernetes.io/editdocs/)
## Issues Management or Triage
@ -227,15 +208,31 @@ Have you ever noticed the total number of [open issues](https://issues.k8s.io)?
If you haven't noticed by now, we have a large, lively, and friendly open-source community. We depend on new people becoming members and regular code contributors, so we would like you to come join us. To find out more about our community structure, different levels of membership and code contributors, please [explore here](https://github.com/kubernetes/community/tree/master/community-membership.md).
_Improvements needed_
## Communication
* The top level k/community/README.md should be a good starting point for what the community is and does. (see above instructions on rewriting this file)
- [General Information](https://github.com/kubernetes/community/tree/master/communication)
## Events
Kubernetes is the main focus of CloudNativeCon/KubeCon, held twice per year in EMEA and in North America. Information about these and other community events is available on the CNCF [events](https://www.cncf.io/events/) pages.
### Meetups
We follow the general [Cloud Native Computing Foundation guidelines](https://github.com/cncf/meetups) for Meetups. You may also contact Paris Pittman via direct message on Kubernetes Slack (@paris) or by email (parispittman@google.com)
## Mentorship
Please learn about our mentoring initiatives [here](http://git.k8s.io/community/mentoring/README.md).
# Advanced Topics
This section includes things that need to be documented, but typical contributors do not need to interact with regularly.
- [OWNERS files](https://github.com/kubernetes/community/tree/master/contributors/guide/owners.md) - The Kubernetes organizations are managed with OWNERS files, which outline which parts of the code are owned by what groups.
EMEA and in North America. Information about these and other community events is available on the CNCF [events](https://www.cncf.io/events/) pages.
### Meetups
_Improvements needed_
* include link to meetups
* information on CNCF support for founding a Meetup

249
docs/imported/community/keps.md
View File

@ -1,32 +1,26 @@
---
title: Kubernetes Enhancement Proposal Process
---
## Metadata
```
---
kep-number: 1
title: Kubernetes Enhancement Proposal Process
authors:
- name: Caleb Miles
github: calebamiles
slack: calebamiles
- name: Joe Beda
github: jbeda
email: joe@heptio.com
slack: jbeda
- "@calebamiles"
- "@jbeda"
owning-sig: sig-architecture
participating-sigs:
- `kubernetes-wide`
- kubernetes-wide
reviewers:
- name: TBD
- name: "@timothysc"
approvers:
- name: TBD
- name: "@bgrant0607"
editor:
name: TBD
name: "@jbeda"
creation-date: 2017-08-22
status: draft
```
status: implementable
---
# Kubernetes Enhancement Proposal Process
## Table of Contents
@ -63,15 +57,14 @@ A standardized development process for Kubernetes is proposed in order to
- support the creation of _high value user facing_ information such as:
- an overall project development roadmap
- motivation for impactful user facing changes
- support development across multiple repositories beyond `kubernetes/kubernetes`
- reserve GitHub issues for tracking work in flight rather than creating "umbrella"
issues
- ensure community participants are successfully able to drive changes to
completion across one or more releases while stakeholders are adequately
represented throughout the process
This process is supported by a unit of work called a Kubernetes Enhancement
Proposal or KEP. A KEP attempts to combine aspects of a
This process is supported by a unit of work called a Kubernetes Enhancement Proposal or KEP.
A KEP attempts to combine aspects of a
- feature, and effort tracking document
- a product requirements document
@ -91,15 +84,7 @@ and communicate upcoming changes to Kubernetes. In a blog post describing the
> in a way that someone working in a different environment can understand
as a project it is vital to be able to track the chain of custody for a proposed
enhancement from conception through implementation. This proposal does not
attempt to mandate how SIGs track their work internally, however, it is
suggested that SIGs which do not adhere to a process which allows for their hard
work to be explained to others in the wider Kubernetes community will see their
work wallow in the shadows of obscurity. At the very least [survey data][]
suggest that high quality documentation is crucial to project adoption.
Documentation can take many forms and it is imperative to ensure that it is easy
to produce high quality user or developer focused documentation for a complex
project like Kubernetes.
enhancement from conception through implementation.
Without a standardized mechanism for describing important enhancements our
talented technical writers and product managers struggle to weave a coherent
@ -119,9 +104,7 @@ contained in [design proposals][] is both clear and efficient. The KEP process
is intended to create high quality uniform design and implementation documents
for SIGs to deliberate.
[tell a story]: https://blog.rust-lang.org/2017/08/31/Rust-1.20.html
[road to Go 2]: https://blog.golang.org/toward-go2
[survey data]: http://opensourcesurvey.org/2017/
[design proposals]: /contributors/design-proposals
@ -133,8 +116,7 @@ The definition of what constitutes an "enhancement" is a foundational concern
for the Kubernetes project. Roughly any Kubernetes user or operator facing
enhancement should follow the KEP process: if an enhancement would be described
in either written or verbal communication to anyone besides the KEP author or
developer then consider creating a KEP. One concrete example is an enhancement
which should be communicated to SIG Release or SIG PM.
developer then consider creating a KEP.
Similarly, any technical effort (refactoring, major architectural change) that
will impact a large section of the development community should also be
@ -151,11 +133,16 @@ proposing governance changes. However, as changes start impacting other SIGs or
the larger developer community outside of a SIG, the KEP process should be used
to coordinate and communicate.
Enhancements that have major impacts on multiple SIGs should use the KEP process.
A single SIG will own the KEP but it is expected that the set of approvers will span the impacted SIGs.
The KEP process is the way that SIGs can negotiate and communicate changes that cross boundaries.
KEPs will also be used to drive large changes that will cut across all parts of the project.
These KEPs will be owned by SIG-architecture and should be seen as a way to communicate the most fundamental aspects of what Kubernetes is.
### KEP Template
The template for a KEP is precisely defined in the [template proposal][]
[template proposal]: https://github.com/kubernetes/community/pull/1124
The template for a KEP is precisely defined [here](https://github.com/kubernetes/community/tree/master/keps/0000-kep-template.md)
### KEP Metadata
@ -180,18 +167,16 @@ Metadata items:
KEP filename. See the template for instructions and details.
* **status** Required
* The current state of the KEP.
* Must be one of `Draft`, `Deferred`, `Approved`, `Rejected`, `Withdrawn`,
`Final`, `Replaced`.
* Must be one of `provisional`, `implementable`, `implemented`, `deferred`, `rejected`, `withdrawn`, or `replaced`.
* **authors** Required
* A list of authors for the KEP. We require a name (which can be a pseudonym)
along with a github ID. Other ways to contact the author is strongly
encouraged. This is a list of maps. Subkeys of each item: `name`,
`github`, `email` (optional), `slack` (optional).
* A list of authors for the KEP.
This is simply the github ID.
In the future we may enhance this to include other types of identification.
* **owning-sig** Required
* The SIG that is most closely associated with this KEP. If there is code or
other artifacts that will result from this KEP, then it is expected that
this SIG will take responsibility for the bulk of those artifacts.
* SIGs are listed as `sig-abc-def` where the name matches up with the
* Sigs are listed as `sig-abc-def` where the name matches up with the
directory in the `kubernetes/community` repo.
* **participating-sigs** Optional
* A list of SIGs that are involved or impacted by this KEP.
@ -201,8 +186,15 @@ Metadata items:
* Reviewer(s) chosen after triage according to proposal process
* If not yet chosen replace with `TBD`
* Same name/contact scheme as `authors`
* Reviewers should be a distinct set from authors.
* **approvers** Required
* Approver(s) chosen after triage according to proposal process
* Approver(s) are drawn from the impacted SIGs.
It is up to the individual SIGs to determine how they pick approvers for KEPs impacting them.
The approvers are speaking for the SIG in the process of approving this KEP.
The SIGs in question can modify this list as necessary.
* The approvers are the individuals that make the call to move this KEP to the `approved` state.
* Approvers should be a distinct set from authors.
* If not yet chosen replace with `TBD`
* Same name/contact scheme as `authors`
* **editor** Required
@ -231,106 +223,36 @@ Metadata items:
### KEP Workflow
TODO(jbeda) Rationalize this with status entires in the Metadata above.
A KEP has the following states
A KEP is proposed to have the following states
- **opened**: a new KEP has been filed but not triaged by the responsible SIG or
working group
- **accepted**: the motivation has been accepted by the SIG or working group as in
road map
- **scoped**: the design has been approved by the SIG or working group
- **started**: the implementation of the KEP has begun
- **implemented**: the implementation of the KEP is complete
- **deferred**: the KEP has been postponed by the SIG or working group despite
agreement on the motivation
- **superseded**: the KEP has been superseded by another KEP
- **retired**: the implementation of the KEP has been removed
- **rejected**: the KEP has been rejected by the SIG or working group
- **orphaned**: the author or developer of the KEP is no longer willing or able
to complete implementation
with possible paths through the state space
- opened -> deferred (a)
- opened -> rejected (b)
- opened -> orphaned (c)
- opened -> accepted -> orphaned (d)
- opened -> accepted -> scoped -> superseded (e)
- opened -> accepted -> scoped -> orphaned (f)
- opened -> accepted -> scoped -> started -> retired (g)
- opened -> accepted -> scoped -> started -> orphaned (h)
- opened -> accepted -> scoped -> started -> superseded (i)
- opened -> accepted -> scoped -> started -> implemented (j)
- opened -> accepted -> scoped -> started -> implemented -> retired (k)
the happy path is denoted by (j) where an KEP is opened; accepted by a SIG as in
their roadmap; fleshed out with a design; started; and finally implemented. As
Kubernetes continues to mature, hopefully metrics on the utilization of features
will drive decisions on what features to maintain and which to deprecate and so
it is possible that a KEP would be retired if its functionality no longer provides
sufficient value to the community.
- `provisional`: The KEP has been proposed and is actively being defined.
This is the starting state while the KEP is being fleshed out and actively defined and discussed.
The owning SIG has accepted that this is work that needs to be done.
- `implementable`: The approvers have approved this KEP for implementation.
- `implemented`: The KEP has been implemented and is no longer actively changed.
- `deferred`: The KEP is proposed but not actively being worked on.
- `rejected`: The approvers and authors have decided that this KEP is not moving forward.
The KEP is kept around as a historical document.
- `withdrawn`: The KEP has been withdrawn by the authors.
- `replaced`: The KEP has been replaced by a new KEP.
The `superseded-by` metadata value should point to the new KEP.
### Git and GitHub Implementation
Practically an KEP would be implemented as a pull request to a central repository
with the following example structure
KEPs are checked into the community repo under the `/kep` directory.
In the future, as needed we can add SIG specific subdirectories.
KEPs in SIG specific subdirectories have limited impact outside of the SIG and can leverage SIG specific OWNERS files.
```
├── 0000-kep-template.md
├── CODEOWNERS
├── index.md
├── sig-architecture
│   ├── deferred
│   ├── orphaned
│   └── retired
├── sig-network
│   ├── deferred
│   ├── kube-dns
│   ├── orphaned
│   └── retired
├── sig-node
│   ├── deferred
│   ├── kubelet
│   ├── orphaned
│   └── retired
├── sig-release
│   ├── deferred
│   ├── orphaned
│   └── retired
├── sig-storage
│   ├── deferred
│   ├── orphaned
│   └── retired
├── unsorted-to-be-used-by-newcomers-only
└── wg-resource-management
├── deferred
├── orphaned
└── retired
```
where each SIG or working group is given a top level directory with subprojects
maintained by the SIG listed in sub directories. For newcomers to the community
an `unsorted-to-be-used-by-newcomers-only` directory may be used before an KEP
can be properly routed to a SIG although hopefully if discussion for a potential
KEP begins on the mailing lists proper routing information will be provided to
the KEP author. Additionally a top level index of KEPs may be helpful for people
looking for a complete list of KEPs. There should be basic CI to ensure that an
`index.md` remains up to date.
Ideally no work would begin within the repositories of the Kubernetes organization
before a KEP has been approved by the responsible SIG or working group. While the
details of how SIGs organize their work is beyond the scope of this proposal one
possibility would be for each charter SIG to create a top level repository within
the Kubernetes org where implementation issues managed by that SIG would be filed.
New KEPs can be checked in with a file name in the form of `draft-YYYYMMDD-my-title.md`.
As significant work is done on the KEP the authors can assign a KEP number.
This is done by taking the next number in the NEXT_KEP_NUMBER file, incrementing that number, and renaming the KEP.
No other changes should be put in that PR so that it can be approved quickly and minimize merge conflicts.
The KEP number can also be done as part of the initial submission if the PR is likely to be uncontested and merged quickly.
### KEP Editor Role
Taking a cue from the [Python PEP process][], I believe that a group of KEP editors
will be required to make this process successful; the job of an KEP editor is
likely very similar to the [PEP editor responsibilities][] and will hopefully
provide another opportunity for people who do not write code daily to contribute
to Kubernetes.
Taking a cue from the [Python PEP process][], we define the role of a KEP editor.
The job of an KEP editor is likely very similar to the [PEP editor responsibilities][] and will hopefully provide another opportunity for people who do not write code daily to contribute to Kubernetes.
In keeping with the PEP editors which
@ -340,8 +262,8 @@ In keeping with the PEP editors which
> Edit the PEP for language (spelling, grammar, sentence structure, etc.), markup
> (for reST PEPs), code style (examples should match PEP 8 & 7).
KEP editors should generally not pass judgement on a KEP beyond editorial
corrections.
KEP editors should generally not pass judgement on a KEP beyond editorial corrections.
KEP editors can also help inform authors about the process and otherwise help things move smoothly.
[Python PEP process]: https://www.python.org/dev/peps/pep-0001/
[PEP editor responsibilities]: https://www.python.org/dev/peps/pep-0001/#pep-editor-responsibilities-workflow
@ -351,7 +273,7 @@ corrections.
It is proposed that the primary metrics which would signal the success or
failure of the KEP process are
- how many "features" are tracked with a KEP
- how many "enhancements" are tracked with a KEP
- distribution of time a KEP spends in each state
- KEP rejection rate
- PRs referencing a KEP merged per week
@ -364,18 +286,11 @@ failure of the KEP process are
### Prior Art
The KEP process as proposed was essentially stolen from the [Rust RFC process] which
The KEP process as proposed was essentially stolen from the [Rust RFC process][] which
itself seems to be very similar to the [Python PEP process][]
[Rust RFC process]: https://github.com/rust-lang/rfcs
## Graduation Criteria
should hit at least the following milestones
- a release note draft can be generated by referring primarily to KEP content
- a yearly road map is expressed as a KEP
## Drawbacks
Any additional process has the potential to engender resentment within the
@ -444,6 +359,50 @@ and durable storage.
## Unresolved Questions
- How reviewers and approvers are assigned to a KEP
- Example schedule, deadline, and time frame for each stage of a KEP
- Communication/notification mechanisms
- Review meetings and escalation procedure
roadmap][]
- the fact that the [what constitutes a feature][] is still undefined
- [issue management][]
- the difference between an [accepted design and a proposal][]
- [the organization of design proposals][]
this proposal attempts to place these concerns within a general framework.
[architectural roadmap]: https://github.com/kubernetes/community/issues/952
[what constitutes a feature]: https://github.com/kubernetes/community/issues/531
[issue management]: https://github.com/kubernetes/community/issues/580
[accepted design and a proposal]: https://github.com/kubernetes/community/issues/914
[the organization of design proposals]: https://github.com/kubernetes/community/issues/918
### Github issues vs. KEPs
The use of GitHub issues when proposing changes does not provide SIGs good
facilities for signaling approval or rejection of a proposed change to Kubernetes
since anyone can open a GitHub issue at any time. Additionally managing a proposed
change across multiple releases is somewhat cumbersome as labels and milestones
need to be updated for every release that a change spans. These long lived GitHub
issues lead to an ever increasing number of issues open against
`kubernetes/features` which itself has become a management problem.
In addition to the challenge of managing issues over time, searching for text
within an issue can be challenging. The flat hierarchy of issues can also make
navigation and categorization tricky. While not all community members might
not be comfortable using Git directly, it is imperative that as a community we
work to educate people on a standard set of tools so they can take their
experience to other projects they may decide to work on in the future. While
git is a fantastic version control system (VCS), it is not a project management
tool nor a cogent way of managing an architectural catalog or backlog; this
proposal is limited to motivating the creation of a standardized definition of
work in order to facilitate project management. This primitive for describing
a unit of work may also allow contributors to create their own personalized
view of the state of the project while relying on Git and GitHub for consistency
and durable storage.
## Unresolved Questions
- How reviewers and approvers are assigned to a KEP
- Approval decision process for a KEP
- Example schedule, deadline, and time frame for each stage of a KEP

32
docs/imported/community/mentoring.md
View File

@ -1,41 +1,49 @@
---
title: Kubernetes Mentoring Initiatives
notitle: true
---
# Kubernetes Mentoring Initiatives
This folder will be used for all mentoring initiatives for Kubernetes.
---
## Kubernetes Pilots
We understand that everyone has different learning styles and we want to support as many of those as possible. Mentoring is vital to the growth of an individual and organization of every kind. For Kubernetes, the larger the project becomes, it's necessary to keep a continuous pipeline of quality contributors.
We understand that everyone has different learning styles and we want to support as many of those as possible. Mentoring is vital to the growth of an individual and organization of every kind. For Kubernetes, the larger the project becomes, it's necessary to keep a continuous pipeline of quality contributors.
*What's a Pilot?*
A pilot is a Kubernetes mentor helping new and current members navigate the seas of our repos.
## Current mentoring activities:
All are currently in an incubation phase. Please reach out to Paris Pittman (parispittman@google.com or Paris on Kubernetes slack channel) for more information on how to get involved. The preliminary deck for mentoring strategies is [here](https://docs.google.com/presentation/d/1bRjDEPEn3autWzaEFirbLfHagbZV04Q9kTCalYmnnXw/edit?usp=sharing0).
All are currently in an incubation phase. Please reach out to Paris Pittman (parispittman@google.com or Paris on Kubernetes slack channel) for more information on how to get involved.
[Contributor Office Hours](https://github.com/kubernetes/community/blob/master/events/office-hours.md)
[Group Mentoring Cohorts](https://github.com/kubernetes/community/tree/master/mentoring/group-mentoring.md)
[Outreachy](https://github.com/kubernetes/community/tree/master/sig-cli/outreachy.md)
Mentors On Demand
* [Meet Our Contributors](https://github.com/kubernetes/community/tree/master/mentoring/meet-our-contributors.md)
Long Term Contributor Ladder Growth
* [Group Mentoring Cohorts](https://github.com/kubernetes/community/tree/master/mentoring/group-mentoring.md)
Students
* [Outreachy](https://github.com/kubernetes/community/tree/master/sig-cli/outreachy.md)
* [Google Summer of Code](https://github.com/kubernetes/community/tree/master/mentoring/google-summer-of-code.md)
#### Inspiration and Thanks
This is not an out of the box program but was largely inspired by the following:
* [Ada Developer Academy](https://adadevelopersacademy.org/)
* [Apache Mentoring Programme](https://community.apache.org/mentoringprogramme.html)
* [exercism.io](https://github.com/OperationCode/exercism-io-mentoring)
* [Google Summer of Code](https://developers.google.com/open-source/gsoc/)
* [exercism.io](https://github.com/OperationCode/exercism-io-mentoring)
* [OpenStack Mentoring](https://wiki.openstack.org/wiki/Mentoring)
* [Apache Mentoring Programme](https://community.apache.org/mentoringprogramme.html)
* [Outreachy](https://www.outreachy.org/)
* [OpenStack Mentoring](https://wiki.openstack.org/wiki/Mentoring)
Thanks to:
* the many contributors who reviewed and participated in brainstorming,
* founding mentees for their willingness to try this out,
* founding Pilots (@chrislovecnm, @luxas, @kow3ns)
We welcome PRs, suggestions, and help!
welcome PRs, suggestions, and help!
the many contributors who reviewed and participated in brainstorming,
* founding mentees for their willingness to try this out,
try this out,
* founding Pilots (@chrislovecnm, @luxas, @kow3ns)
We welcome PRs, suggestions, and help!