Merge pull request #1584 from jbeda/kep-process

Update KEP process

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).
 

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
+  - "@calebamiles"
-    github: calebamiles
+  - "@jbeda"
-    slack: calebamiles
-  - name: Joe Beda
-    github: jbeda
-    email: joe@heptio.com
-    slack: 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
+This process is supported by a unit of work called a Kubernetes Enhancement Proposal or KEP.
-Proposal or KEP. A KEP attempts to combine aspects of a
+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
+enhancement from conception through implementation.
-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.
 
 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
+developer then consider creating a KEP.
-which should be communicated to SIG Release or SIG PM.
 
 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][]
+The template for a KEP is precisely defined [here](0000-kep-template.md)
-
-[template proposal]: https://github.com/kubernetes/community/pull/1124
 
 ### 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`,
+  * Must be one of `accepted`, `implementable`, `implemented`, `deferred`, `rejected`, `withdrawn`, or `replaced`.
-    `Final`, `Replaced`.
 * **authors** Required
-  * A list of authors for the KEP.  We require a name (which can be a psuedonym)
+  * A list of authors for the KEP.
-    along with a github ID.  Other ways to contact the author is strongly
+    This is simply the github ID.
-    encouraged.  This is a list of maps.  Subkeys of each item: `name`,
+    In the future we may enhance this to include other types of identification.
-    `github`, `email` (optional), `slack` (optional).
 * **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
+- `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.
-- **opened**: a new KEP has been filed but not triaged by the responsible SIG or
+  The owning SIG has accepted that this is work that needs to be done.
-  working group
+- `implementable`: The approvers have approved this KEP for implementation.
-- **accepted**: the motivation has been accepted by the SIG or working group as in
+- `implemented`: The KEP has been implemented and is no longer actively changed.
-  road map
+- `deferred`: The KEP is proposed but not actively being worked on.
-- **scoped**: the design has been approved by the SIG or working group
+- `rejected`: The approvers and authors have decided that this KEP is not moving forward.
-- **started**: the implementation of the KEP has begun
+  The KEP is kept around as a historical document.
-- **implemented**: the implementation of the KEP is complete
+- `withdrawn`: The KEP has been withdrawn by the authors.
-- **deferred**: the KEP has been postponed by the SIG or working group despite
+- `replaced`: The KEP has been replaced by a new KEP.
-  agreement on the motivation
+  The `superseded-by` metadata value should point to the new KEP.
-- **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.
 
 ### Git and GitHub Implementation
 
-Practically an KEP would be implemented as a pull request to a central repository
+KEPs are checked into the community repo under the `/kep` directory.
-with the following example structure
+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.
 
-```
+New KEPs can be checked in with a file name in the form of `draft-YYYYMMDD-my-title.md`.
-├── 0000-kep-template.md
+As significant work is done on the KEP the authors can assign a KEP number.
-├── CODEOWNERS
+This is done by taking the next number in the NEXT_KEP_NUMBER file, incrementing that number, and renaming the KEP.
-├── index.md
+No other changes should be put in that PR so that it can be approved quickly and minimize merge conflicts.
-├── sig-architecture
+The KEP number can also be done as part of the initial submission if the PR is likely to be uncontested and merged quickly.
-│   ├── 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.
 
 ### KEP Editor Role
 
-Taking a cue from the [Python PEP process][], I believe that a group of KEP editors
+Taking a cue from the [Python PEP process][], we define the role of a KEP editor.
-will be required to make this process successful; the job of an KEP editor is
+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.
-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
+KEP editors should generally not pass judgement on a KEP beyond editorial corrections.
-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"

keps/NEXT_KEP_NUMBER

@@ -0,0 +1 @@
+2

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
+See [KEP-1](1-kubernetes-enhancement-proposal-process.md) for details of this process.
-
-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.