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

Merge pull request #1584 from jbeda/kep-process 

Update KEP process
This commit is contained in:
k8s-ci-robot 2018-01-18 08:45:35 -08:00 committed by GitHub
parent 8ab61ca524 891be571d1
commit d7cb3a8fe3
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 66 additions and 172 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
keps/0000-kep-template.md
View File

@ -16,7 +16,7 @@ approvers:
editor: TBD
creation-date: yyyy-mm-dd
last-updated: yyyy-mm-dd
status: draft
status: accepted
see-also:
- KEP-1
- KEP-2
@ -37,7 +37,7 @@ The title should be lowercased and spaces/punctuation should be replaced with `-
As the KEP is approved and an official KEP number is allocated, the file should be renamed.
To get started with this template:
* Make a copy in the appropriate directory.
* Make a copy of this template.
Name it `draft-YYYYMMDD-my-title.md`.
* Create a PR in the [`kubernetes/community`](https://github.com/kubernetes/community) repo.
* Check in early.
@ -45,7 +45,8 @@ To get started with this template:
View anything marked as a draft as a working document.
Aim for single topic PRs to keep discussions focused.
If you disagree with what is already in a document, open a new PR with suggested changes.
* As a KEP is approved, rename the file yet again with the final KEP number.
* A KEP number can be assigned at any time by (even in the first PR) (a) taking the next number in the NEXT_KEP_NUMBER file and (b) incrementing that number.
These PRs should be approved quickly to minimize merge conflicts.
The canonical place for the latest set of instructions (and the likely source of this file) is [here](/keps/0000-kep-template.md).

216
keps/1-kubernetes-enhancement-proposal-process.md → keps/001-kubernetes-enhancement-proposal-process.md
View File

@ -1,30 +1,23 @@
# 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: accepted
---
# Kubernetes Enhancement Proposal Process
## Table of Contents
@ -61,15 +54,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
@ -89,15 +81,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
@ -117,9 +101,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
@ -131,8 +113,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
@ -149,11 +130,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](0000-kep-template.md)
### KEP Metadata
@ -178,13 +164,11 @@ 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 `accepted`, `implementable`, `implemented`, `deferred`, `rejected`, `withdrawn`, or `replaced`.
* **authors** Required
* A list of authors for the KEP. We require a name (which can be a psuedonym)
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
@ -199,8 +183,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
@ -229,106 +220,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.
- `accepted`: 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
@ -338,8 +259,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
@ -349,7 +270,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
@ -362,18 +283,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
@ -443,16 +357,6 @@ 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
- Communication/notification mechanisms
- Review meetings and escalation procedure
- Decision on where development should occur
## Mentors
- caleb miles
- github: [calebamiles](https://github.com/calebamiles/)
- slack: [calebamiles](https://coreos.slack.com/team/caleb.miles)
- email: [caleb.miles@coreos.com](mailto:caleb.miles@coreos.com)
- pronoun: "he"
- Review meetings and escalation procedure

1
keps/NEXT_KEP_NUMBER Normal file
View File

@ -0,0 +1 @@
2

14
keps/README.md
View File

@ -4,16 +4,4 @@ This directory contains both the template and process for KEPs.
This process is still in an _alpha_ state and is opt-in for those that want to provide feedback for the process.
## Directory structure
Most KEPs will be sponsored out of a specific SIG. Those can be incubated inside of a subdirectory here for that SIG. SIGs can add those directories and OWNERs files on an as needed basis.
Any KEPs that cross many SIG boundaries can be created at the root of the KEP directory.
## KEP numbering
The next dense number KEP will be 2.
To assign a number create a commit that both renames the KEP file and updates this file.
In process KEPs can use a date based numbering scheme. See [KEP-1](1-kubernetes-enhancement-proposal-process.md) for details of this process.
See [KEP-1](1-kubernetes-enhancement-proposal-process.md) for details of this process.