diff --git a/keps/0000-kep-template.md b/keps/0000-kep-template.md index 4494b7b3c..105d3f6a6 100644 --- a/keps/0000-kep-template.md +++ b/keps/0000-kep-template.md @@ -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). diff --git a/keps/1-kubernetes-enhancement-proposal-process.md b/keps/001-kubernetes-enhancement-proposal-process.md similarity index 67% rename from keps/1-kubernetes-enhancement-proposal-process.md rename to keps/001-kubernetes-enhancement-proposal-process.md index 6f8084025..895b38255 100644 --- a/keps/1-kubernetes-enhancement-proposal-process.md +++ b/keps/001-kubernetes-enhancement-proposal-process.md @@ -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 \ No newline at end of file diff --git a/keps/NEXT_KEP_NUMBER b/keps/NEXT_KEP_NUMBER new file mode 100644 index 000000000..d8263ee98 --- /dev/null +++ b/keps/NEXT_KEP_NUMBER @@ -0,0 +1 @@ +2 \ No newline at end of file diff --git a/keps/README.md b/keps/README.md index 72487d8bf..e9397475d 100644 --- a/keps/README.md +++ b/keps/README.md @@ -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. \ No newline at end of file +See [KEP-1](1-kubernetes-enhancement-proposal-process.md) for details of this process. \ No newline at end of file