Merge pull request #1401 from jbeda/kep-update

Automatic merge from submit-queue.

KEP template update

This is based on input from @timothysc.  Still need to reconcile this with the instructions.

1 files changed, 91 insertions, 124 deletions

diff --git a/contributors/design-proposals/architecture/0000-kep-template.md b/contributors/design-proposals/architecture/0000-kep-template.md
index 764fff73..45783f8d 100644
--- a/contributors/design-proposals/architecture/0000-kep-template.md
+++ b/contributors/design-proposals/architecture/0000-kep-template.md
@@ -1,67 +1,19 @@
-# Title
-
-This is the title of the KEP.  Keep it simple and descriptive. A good title can
-help communicate what the KEP is and should be considered as part of any review.
-
-The *filename* for the KEP should include the KEP number along with the title.
-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.  Name it `draft-YYYYMMDD-my-title.md`.
-* Create a PR in the
-  [`kubernetes/community`](https://github.com/kubernetes/community) repo.
-* Check in early.  Do this once the document holds together and general
-  direction is understood by many in the sponsoring SIG. 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.
-
-The canonical place for the latest set of instructions (and the likely source of
-this file) is
-[here](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/architecture/0000-kep-template.md).
-
-## Metadata
-
-The `Metadata` section is intended to support the creation of tooling around the
-KEP process.  This will be a YAML section that is fenced as a code block.
-
-See the KEP process for details on each of these items.  This is here for easy
-copy/pasting.
-
-TODO(jbeda): Do we want to move this to the front the doc with a delimiter
-(`---`) so it is easier to parse.  Many static site generators use this and call
-it "front matter".
-
-TODO(jbeda): Do we want to have a "people database" to reduce the amount of
-duplication on naming people here?  This would be a simple map of github ID to
-name and contact info.
-
-```yaml
-kep-number: draft-XXX
+---
+kep-number: draft-YYYYMMDD
 title: My First KEP
 authors:
-  - name: Jane Doe
-    github: janedoe
-    email: janedoe@example.com
+  - "@janedoe"
 owning-sig: sig-xxx
 participating-sigs:
   - sig-aaa
   - sig-bbb
 reviewers:
-  - name: TBD
-  # - name: Alice Doe
-  #   github: alicedoe
-  #   email: alicedoe@example.com
+  - TBD
+  - "@alicedoe"
 approvers:
-  - name: TBD
-  # - name: Oscar Doe
-  #   github: oscardoe
-  #   email: oscardoe@example.com
-editor:
-  name: TBD
+  - TBD
+  - "@oscardoe"
+editor: TBD
 creation-date: yyyy-mm-dd
 last-updated: yyyy-mm-dd
 status: draft
@@ -72,97 +24,126 @@ replaces:
   - KEP-3
 superseded-by:
   - KEP-100
-```
+---
+
+# Title
+
+This is the title of the KEP.
+Keep it simple and descriptive.
+A good title can help communicate what the KEP is and should be considered as part of any review.
+
+The *filename* for the KEP should include the KEP number along with the title.
+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.
+  Name it `draft-YYYYMMDD-my-title.md`.
+* Create a PR in the [`kubernetes/community`](https://github.com/kubernetes/community) repo.
+* Check in early.
+  Do this once the document holds together and general direction is understood by many in the sponsoring SIG.
+  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.
+
+The canonical place for the latest set of instructions (and the likely source of this file) is [here](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/architecture/0000-kep-template.md).
+
+The `Metadata` section above is intended to support the creation of tooling around the KEP process.
+This will be a YAML section that is fenced as a code block.
+See the KEP process for details on each of these items.
 
 ## Table of Contents
 
-A table of contents is helpful for quickly jumping to sections of a KEP and for
-highlighting any additional information provided beyond the standard KEP
-template. [Tools for generating][] a table of contents from markdown are
-available.
+A table of contents is helpful for quickly jumping to sections of a KEP and for highlighting any additional information provided beyond the standard KEP template.
+[Tools for generating][] a table of contents from markdown are available.
+
+
+* [Table of Contents](#table-of-contents)
+* [Summary](#summary)
+* [Motivation](#motivation)
+    * [Goals](#goals)
+    * [Non-Goals](#non-goals)
+* [Proposal](#proposal)
+    * [User Stories [optional]](#user-stories-optional)
+      * [Story 1](#story-1)
+      * [Story 2](#story-2)
+    * [Implementation Details/Notes/Constraints [optional]](#implementation-detailsnotesconstraints-optional)
+    * [Security Considerations](#security-considerations)
+* [Graduation Criteria](#graduation-criteria)
+* [Implementation History](#implementation-history)
+* [Drawbacks [optional]](#drawbacks-optional)
+* [Alternatives [optional]](#alternatives-optional)
+
 
 [Tools for generating]: https://github.com/ekalinin/github-markdown-toc
 
 ## Summary
 
-The `Summary` section is incredibly important for producing high quality user
-focused documentation such as release notes or a development road map. It should
-be possible to collect this information before implementation begins in order
-to avoid requiring implementors to split their attention between writing
-release notes and implementing the feature itself. KEP editors, SIG Docs, and
-SIG PM should help to ensure that the tone and content of the `Summary` section
-is useful for a wide audience.
+The `Summary` section is incredibly important for producing high quality user focused documentation such as release notes or a development road map.
+It should be possible to collect this information before implementation begins in order to avoid requiring implementors to split their attention between writing release notes and implementing the feature itself.
+KEP editors, SIG Docs, and SIG PM should help to ensure that the tone and content of the `Summary` section is useful for a wide audience.
 
 A good summary is probably at least a paragraph in length.
 
 ## Motivation
 
-The `Motivation` section should describe
+This section is for explicitly listing the motivation, goals and non-goals of this KEP.
+Describe why the change is important and the benefits to users.
+The motivation section can optionally provide links to [experience reports][] to demonstrate the interest in a KEP within the wider Kubernetes community.
 
-- why we believe this change is important
-- what benefits are expected to be realized from the change
-- the high level design goals
+[experience reports]: https://github.com/golang/go/wiki/ExperienceReports
 
-The `Motivation` section is important for getting all responsible parties to
-understand the intention behind a change. The motivation section can optionally
-provide links to [experience reports][] to demonstrate the interest in a KEP
-within the wider Kubernetes community.
+### Goals
 
-[experience reports]: https://github.com/golang/go/wiki/ExperienceReports
+List the specific goals of the KEP.
+How will we know that this has succeeded?
 
-## Guide-level Explanation [optional]
+### Non-Goals
 
-Merging a change to source control is a crucial, but not final, milestone in
-the implementation of a KEP. Enhancements need to be explained to the Kubernetes
-community. The `Guide-level Explaination` section should be used to explain a
-KEP to another Kubernaut after implementation. Excellent guidance can be
-found in the Rust RFC [guide-level explanation][] instructions.
+What is out of scope for his KEP?
+Listing non-goals helps to focus discussion and make progress.
 
+## Proposal
 
-[guide-level explanation]: https://github.com/rust-lang/rfcs/blob/master/0000-template.md#guide-level-explanation
+This is where we get down to the nitty gritty of what the proposal actually is.
 
+### User Stories [optional]
 
-## Reference-level explanation
+Detail the things that people will be able to do if this KEP is implemented.
+Include as much detail as possible so that people can understand the "how" of the system.
+The goal here is to make this feel real for users without getting bogged down.
 
-Before submitting a detailed implementation plan, a KEP author might begin the
-`Reference-level Explaination` by sketching high level design goals and any
-mandatory requirements.
+#### Story 1
 
-Communicating dependencies across multiple SIGs is an important use for KEPs.
-Explaining how a KEP interacts with other KEPs and existing Kubernetes
-functionality should be included in this section.
+#### Story 2
 
-The `Reference-level explaination` section should ideally contain enough
-information for someone besides the author to begin working on an implementation
-of the KEP. In a similar manner to the guidance on [implementing an RFC][] from
-the Rust community, not all KEPs must be implemented immediately. Associating
-each KEP with one or more issues filed against Kubernetes repositories allows
-interested community members to track implementation.
+### Implementation Details/Notes/Constraints [optional]
 
-Excellent guidance can be found in the Rust RFC [reference-level explanation][]
-instructions.
+What are the caveats to the implementation?
+What are some important details that didn't come across above.
+Go in to as much detail as necessary here.
+This might be a good place to talk about core concepts and how they releate.
 
-[reference-level explaination]: https://github.com/rust-lang/rfcs/blob/master/0000-template.md#reference-level-explanation
+### Security Considerations
 
-[implementing an RFC]: https://github.com/rust-lang/rfcs/blob/master/README.md#implementing-an-rfc
+Make sure that you consider the impact of this feature from the point of view of Security.
 
 ## Graduation Criteria
 
-Gathering user feedback is crucial for building high quality experiences and
-SIGs have the important responsibility of setting milestones for stability
-and completeness. Hopefully the content previously contained in
-[umbrella issues][] will be tracked in the `Graduation Criteria` section.
+How will we know that this has succeeded?
+Gathering user feedback is crucial for building high quality experiences and SIGs have the important responsibility of setting milestones for stability and completeness.
+Hopefully the content previously contained in [umbrella issues][] will be tracked in the `Graduation Criteria` section.
 
 [umbrella issues]: https://github.com/kubernetes/kubernetes/issues/42752
 
 ## Implementation History
 
-Major milestones in the life cycle of a KEP should be tracked in
-`Implementation History`. Major milestones might include
+Major milestones in the life cycle of a KEP should be tracked in `Implementation History`.
+Major milestones might include
 
 - the `Summary` and `Motivation` sections being merged signaling SIG acceptance
-- the `Detailed Design` section being merged signaling agreement on a proposed
-  design
+- the `Proposal` section being merged signaling agreement on a proposed design
 - the date implementation started
 - the first Kubernetes release where an initial version of the KEP was available
 - the version of Kubernetes where the KEP graduated to general availability
@@ -174,18 +155,4 @@ Why should this KEP _not_ be implemented.
 
 ## Alternatives [optional]
 
-Similar to the `Drawbacks` section the `Alternatives` section is used to
-highlight and record other possible approaches to delivering the value proposed
-by a KEP.
-
-## Unresolved Questions [optional]
-
-The `Unresolved Questions` section is used to parking lot issues not ready to be
-addressed before implementation begins.
-
-## Mentors [optional]
-
-Mentors who can help a community member implement a KEP which follows its
-`Detailed Design` are crucial to scaling the Kubernetes project. Potential
-mentors can list their contact information using their preferred contact
-information in the `Mentors` section.
+Similar to the `Drawbacks` section the `Alternatives` section is used to highlight and record other possible approaches to delivering the value proposed by a KEP.