Merge pull request #1813 from jbeda/kep-update

Update/clarify KEP process

keps/0000-kep-template.md

@@ -1,5 +1,5 @@
 ---
-kep-number: draft-YYYYMMDD
+kep-number: 0
 title: My First KEP
 authors:
   - "@janedoe"
@@ -16,7 +16,7 @@ approvers:
 editor: TBD
 creation-date: yyyy-mm-dd
 last-updated: yyyy-mm-dd
-status: accepted
+status: provisional
 see-also:
   - KEP-1
   - KEP-2
@@ -37,16 +37,25 @@ 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 of this template.
+1. **Pick a hosting SIG.**
-  Name it `draft-YYYYMMDD-my-title.md`.
+  Make sure that the problem space is something the SIG is interested in taking up.
-* Create a PR in the [`kubernetes/community`](https://github.com/kubernetes/community) repo.
+  KEPs should not be checked in without a sponsoring SIG.
-* Check in early.
+1. **Allocate a KEP number.**
-  Do this once the document holds together and general direction is understood by many in the sponsoring SIG.
+  Do this by (a) taking the next number in the `NEXT_KEP_NUMBER` file and (b) incrementing that number.
-  View anything marked as a draft as a working document.
+  Include the updated `NEXT_KEP_NUMBER` file in your PR.
+1. **Make a copy of this template.**
+  Name it `NNNN-YYYYMMDD-my-title.md` where `NNNN` is the KEP number that was allocated.
+1. **Fill out the "overview" sections.**
+  This includes the Summary and Motivation sections.
+  These should be easy if you've preflighted the idea of the KEP with the appropriate SIG.
+1. **Create a PR.**
+  Assign it to folks in the SIG that are sponsoring this process.
+1. **Merge early.**
+  Avoid getting hung up on specific details and instead aim to get the goal of the KEP merged quickly.
+  The best way to do this is to just start with the "Overview" sections and fill out details incrementally in follow on PRs.
+  View anything marked as a `provisional` as a working document and subject to change.
   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.
-* 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/0001-kubernetes-enhancement-proposal-process.md

@@ -164,7 +164,7 @@ Metadata items:
     KEP filename.  See the template for instructions and details.
 * **status** Required
   * The current state of the KEP.
-  * Must be one of `accepted`, `implementable`, `implemented`, `deferred`, `rejected`, `withdrawn`, or `replaced`.
+  * Must be one of `provisional`, `implementable`, `implemented`, `deferred`, `rejected`, `withdrawn`, or `replaced`.
 * **authors** Required
   * A list of authors for the KEP.
     This is simply the github ID.
@@ -222,7 +222,7 @@ Metadata items:
 
 A KEP has the following states
 
-- `accepted`: The KEP has been proposed and is actively being defined.
+- `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.

keps/0002-controller-manager.md

@@ -1,5 +1,5 @@
-```
+---
-kep-number: draft-20171127
+kep-number: 2
 title: Cloud Provider Controller Manager
 authors:
   - "@cheftako"
@@ -15,10 +15,10 @@ reviewers:
 approvers:
   - "@thockin"
 editor: TBD
-status: approved
+status: provisional
 replaces:
   - contributors/design-proposals/cloud-provider/cloud-provider-refactoring.md
-```
+---
 
 # Remove Cloud Provider Code From Kubernetes Core
 

keps/README.md

@@ -1,7 +1,59 @@
 # Kubernetes Enhancement Proposals (KEPs)
 
-This directory contains both the template and process for KEPs.
+A Kubernetes Enhancement Proposal (KEP) is a way to propose, communicate and coordiante on new efforts for the Kubernetes project.
+You can read the full details of the project in [KEP-1](0001-kubernetes-enhancement-proposal-process.md).
 
-This process is still in an _alpha_ state and is opt-in for those that want to provide feedback for the process.
+This process is still in a _beta_ state and is opt-in for those that want to provide feedback for the process.
 
-See [KEP-1](0001-kubernetes-enhancement-proposal-process.md) for details of this process.
+## Quick start for the KEP process
+
+1. Socialize an idea with a sponsoring SIG.
+   Make sure that others think the work is worth taking up and will help review the KEP and any code changes required.
+2. Follow the process outlined in the [KEP template](0000-kep-template.md)
+
+## FAQs
+
+### Do I have to use the KEP process?
+
+No... but we hope that you will.
+Over time having a rich set of KEPs in one place will make it easier for people to track what is going in the community and find a structured historic record.
+
+KEPs are only required when the changes are wide ranging and impact most of the project.
+These changes are usually coordinated through SIG-Architecture.
+It is up to any specific SIG if they want to use the KEP process and when.
+The process is available to SIGs to use but not required.
+
+### Why would I want to use the KEP process?
+
+Our aim with KEPs is to clearly communicate new efforts to the Kubernetes contributor community.
+As such, we want to build a well curated set of clear proposals in a common format with useful metadata.
+
+Benefits to KEP users (in the limit):
+* Exposure on a kubernetes blessed web site that is findable via web search engines.
+* Cross indexing of KEPs so that users can find connections and the current status of any KEP.
+* A clear process with approvers and reviewers for making decisions.
+  This will lead to more structured decisions that stick as there is a discoverable record around the decisions.
+
+We are inspired by IETF RFCs, Pyton PEPs and Rust RFCs.
+See [KEP-1](0001-kubernetes-enhancement-proposal-process.md) for more details.
+
+### Do I put my KEP in the root KEP directory or a SIG subdirectory?
+
+If the KEP is mainly restricted to one SIG's purview then it should be in a KEP directory for that SIG.
+If the KEP is widely impacting much of Kubernetes, it should be put at the root of this directory.
+If in doubt ask [SIG-Architecture](../sig-architecture/README.md) and they can advise.
+
+### What will it take for KEPs to "graduate" out of "beta"?
+
+Things we'd like to see happen to consider KEPs well on their way:
+* A set of KEPs that show healthy process around describing an effort and recording decisions in a reasonable amount of time.
+* KEPs exposed on a searchable and indexable web site.
+* Presubmit checks for KEPs around metadata format and markdown validity.
+
+Even so, the process can evolve. As we find new techniques we can improve our processes.
+
+### My FAQ isn't answered here!
+
+The KEP process is still evolving!
+If something is missing or not answered here feel free to reach out to [SIG-Architecture](../sig-architecture/README.md).
+If you want to propose a change to the KEP process you can open a PR on [KEP-1](0001-kubernetes-enhancement-proposal-process.md) with your proposal.

keps/sig-cluster-lifecycle/0003-cluster-api.md

@@ -1,11 +1,7 @@
-# Kubernetes Cluster Management API
-
-## Metadata
-```
 ---
 kep-number: 3
 title: Kubernetes Cluster Management API
-status: accepted
+status: provisional
 authors:
     - "@roberthbailey"
     - "@pipejakob"
@@ -18,8 +14,9 @@ editor:
   - "@roberthbailey"
 creation-date: 2018-01-19
 last-updated: 2018-01-22
+---
 
-```
+# Kubernetes Cluster Management API
 
 ## Table of Contents
 

keps/sig-cluster-lifecycle/0004-bootstrap-checkpointing.md

@@ -1,7 +1,3 @@
-# Kubernetes Bootstrap Checkpointing Proposal
-
-## Metadata
-```
 ---
 kep-number: 4
 title: Kubernetes Bootstrap Checkpointing Proposal
@@ -22,8 +18,9 @@ editor:
   name: @timothysc
 creation-date: 2017-10-20
 last-updated: 2018-01-23
+---
 
-```
+# Kubernetes Bootstrap Checkpointing Proposal
 
 ## Table of Contents