Merge pull request #1135 from jbeda/kep-metadata

Automatic merge from submit-queue.

KEP metadata

Markdownify KEP metadata proposal that was discussed in https://docs.google.com/document/d/1ynmBMuDuT7yGzRscObB1KtgJj8ljYq0I5q4oshrJUCs/edit?ts=59c1b868#.

Also moved files around so that we are following some of the suggestions here.  Merged the KEP template and the template instructions to reduce the number of files we need to manage.

Author: Kubernetes Submit Queue

Diff for: contributors/design-proposals/architecture/0000-kep-template.md

@@ -1,46 +1,191 @@
-[//]: # ( thank you for creating a KEP! )
-[//]: # ( read the  suggested section content: https://github.com/calebamiles/community/blob/propose-kep-template/contributors/design-proposals/architecture/kep-template-instructions.md )
-[//]: # ( replace `Title` with the KEP title ) 
-[//]: # ( replace section content with your amazing proposal )
-[//]: # ( KEP filename should match title, replace spaces with `- `)
-[//]: # ( update table of contents  before merge )
-[//]: # ( remove comments before merge )
-[//]: # ( profit )
-
 # 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
+title: My First KEP
+authors:
+  - name: Jane Doe
+    github: janedoe
+    email: [email protected]
+owning-sig: sig-xxx
+participating-sigs:
+  - sig-aaa
+  - sig-bbb
+reviewers:
+  - name: TBD
+  # - name: Alice Doe
+  #   github: alicedoe
+  #   email: [email protected]
+approvers:
+  - name: TBD
+  # - name: Oscar Doe
+  #   github: oscardoe
+  #   email: [email protected]
+editor:
+  name: TBD
+creation-date: yyyy-mm-dd
+last-updated: yyyy-mm-dd
+status: draft
+see-also:
+  - KEP-1
+  - KEP-2
+replaces:
+  - KEP-3
+superseded-by:
+  - KEP-100
+```
+
 ## Table of Contents
 
-- [Title](#title)
-   - [Metadata](#metadata)
-   - [Table of Contents](#table-of-contents)
-   - [Summary](#summary)
-   - [Motivation](#motivation)
-   - [Guide-level Explanation](#guide-level-explanation-optional)
-   - [Reference-level explanation](#reference-level-explanation)
-   - [Graduation Criteria](#graduation-criteria)
-   - [Implementation History](#implementation-history)
-   - [Drawbacks](#drawbacks-optional)
-   - [Alternatives](#alternatives-optional)
-   - [Unresolved Questions](#unresolved-questions-optional)
-   - [Mentors](#mentors-optional)
+A table of contents is helpful for quickly jumping to sections of a KEP and for
+highlighting any addtional information provided beyond the standard KEP
+template. [Tools for generating][] a table of contents from markdown are
+available.
+
+[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.
+
+A good summary is probably at least a paragraph in length.
+
 ## Motivation
 
+The `Motivation` section should describe
+
+- why we believe this change is important
+- what benefits are expected to be realized from the change
+- the high level design goals
+
+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.
+
+[experience reports]: https://github.com/golang/go/wiki/ExperienceReports
+
 ## Guide-level Explanation [optional]
 
+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.
+
+
+[guide-level explanation]: https://github.com/rust-lang/rfcs/blob/master/0000-template.md#guide-level-explanation
+
+
 ## Reference-level explanation
 
+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.
+
+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.
+
+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.
+
+Excellent guidance can be found in the Rust RFC [reference-level explanation][]
+instructions.
+
+[reference-level explaination]: https://github.com/rust-lang/rfcs/blob/master/0000-template.md#reference-level-explanation
+
+[implementing an RFC]: https://github.com/rust-lang/rfcs/blob/master/README.md#implementing-an-rfc
+
 ## 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.
+
+[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
+
+- the `Summary` and `Motivation` sections being merged signaling SIG acceptance
+- the `Detailed Design` 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 Kubneretes where the KEP graduated to general availability
+- when the KEP was retired or superseded
+
 ## Drawbacks [optional]
 
+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.

Diff for: contributors/design-proposals/architecture/kubernetes-enhancement-proposal-process.md renamed to contributors/design-proposals/architecture/1-kubernetes-enhancement-proposal-process.md

@@ -3,53 +3,50 @@
 ## Metadata
 ```
 ---
-metadata:
-  number: 0001
-  state: opened
-  authors:
-  - author:
-      name: caleb miles
-      github: @calebamiles
-      slack: @calebamiles
-  owners:
-  - sig-release
-  - sig-pm
-  - sig-architecture
-  - sig-testing
-  - steering-committee
-  links:
-    issues:
-    - [someIssueURL]()
-    prs:
-    - https://github.com/kubernetes/community/pull/967
-    discussions:
-    - https://groups.google.com/forum/#!topic/kubernetes-dev/65A-3ULYPB0
-    - https://groups.google.com/forum/#!topic/kubernetes-sig-architecture/t-1EqeEoLPA
-    documentation:
-    - [someDocsLinkURL]()
-    related:
-    - [KEP template](https://github.com/kubernetes/community/pull/1124)
+kep-number: 1
+title: Kubernetes Enhancement Proposal Process
+authors:
+  - name: Caleb Miles
+    github: calebamiles
+    slack: calebamiles
+  - name: Joe Beda
+    github: jbeda
+    email: [email protected]
+    slack: jbeda
+owning-sig: sig-architecture
+participating-sigs:
+  - `kubernetes-wide`
+reviewers:
+  - name: TBD
+approvers:
+  - name: TBD
+editor:
+  name: TBD
+creation-date: 2017-08-22
+status: draft
 ```
 
 ## Table of Contents
 
-- [Kubernetes Enhancement Proposal Process](#kubernetes-enhancement-proposal-process)
-  - [Metadata](#metadata)
-  - [Summary](#summary)
-  - [Motivation](#motivation)
-  - [Reference-level explanation](#reference-level-explanation)
-     - [What type of work should be tracked by a KEP](#what-type-of-work-should-be-tracked-by-a-kep)
-     - [KEP Template](#kep-template)
-     - [KEP Workflow](#kep-workflow)
-     - [Git and GitHub Implementation](#git-and-github-implementation)
-     - [KEP Editor Role](#kep-editor-role)
-     - [Important Metrics](#important-metrics)
-     - [Prior Art](#prior-art)
-  - [Graduation Criteria](#graduation-criteria)
-  - [Drawbacks](#drawbacks)
-  - [Alternatives](#alternatives)
-  - [Unresolved Questions](#unresolved-questions)
-  - [Mentors](#mentors)
+* [Kubernetes Enhancement Proposal Process](#kubernetes-enhancement-proposal-process)
+  * [Metadata](#metadata)
+  * [Table of Contents](#table-of-contents)
+  * [Summary](#summary)
+  * [Motivation](#motivation)
+  * [Reference-level explanation](#reference-level-explanation)
+      * [What type of work should be tracked by a KEP](#what-type-of-work-should-be-tracked-by-a-kep)
+      * [KEP Template](#kep-template)
+      * [KEP Metadata](#kep-metadata)
+      * [KEP Workflow](#kep-workflow)
+      * [Git and GitHub Implementation](#git-and-github-implementation)
+      * [KEP Editor Role](#kep-editor-role)
+      * [Important Metrics](#important-metrics)
+      * [Prior Art](#prior-art)
+  * [Graduation Criteria](#graduation-criteria)
+  * [Drawbacks](#drawbacks)
+  * [Alternatives](#alternatives)
+  * [Unresolved Questions](#unresolved-questions)
+  * [Mentors](#mentors)
 
 ## Summary
 
@@ -158,8 +155,82 @@ The template for a KEP is precisely defined in the [template proposal][]
 
 [template proposal]: https://github.com/kubernetes/community/pull/1124
 
+### KEP Metadata
+
+There is a place in each KEP for a YAML document that has standard metadata.
+This will be used to support tooling around filtering and display.  It is also
+critical to clearly communicate the status of a KEP.
+
+Metadata items:
+* **kep-number** Required
+  * Each proposal has a number.  This is to make all references to proposals as
+    clear as possible.  This is especially important as we create a network
+    cross references between proposals.
+  * Before having the `Approved` status, the number for the KEP will be in the
+    form of `draft-YYYYMMDD`.  The `YYYYMMDD` is replaced with the current date
+    when first creating the KEP.  The goal is to enable fast parallel merges of
+    pre-acceptance KEPs.
+  * On acceptance a sequential dense number will be assigned.  This will be done
+    by the editor and will be done in such a way as to minimize the chances of
+    conficts.  The final number for a KEP will have no prefix.
+* **title** Required
+  * The title of the KEP in plain language.  The title will also be used in the
+    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`.
+* **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).
+* **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
+    this SIG will take responsiblity for the bulk of those artificats.
+  * Sigs are listed as `sig-abc-def` where the name matches up with the
+    directory in the `kubernetes/community` repo.
+* **participating-sigs** Optional
+  * A list of SIGs that are involved or impacted by this KEP.
+  * A special value of `kubernetes-wide` will indicate that this KEP has impact
+    across the entire project.
+* **reviewers** Required
+  * Reviewer(s) chosen after triage according to proposal process
+  * If not yet chosen replace with `TBD`
+  * Same name/contact scheme as `authors`
+* **approvers** Required
+  * Approver(s) chosen after triage according to proposal process
+  * If not yet chosen replace with `TBD`
+  * Same name/contact scheme as `authors`
+* **editor** Required
+  * Someone to keep things moving forward.
+  * If not yet chosen replace with `TBD`
+  * Same name/contact scheme as `authors`
+* **creation-date** Required
+  * The date that the KEP was first submitted in a PR.
+  * In the form `yyyy-mm-dd`
+  * While this info will also be in source control, it is helpful to have the set of KEP files stand on their own.
+* **last-updated** Optional
+  * The date that the KEP was last changed significantly.
+  * In the form `yyyy-mm-dd`
+* **see-also** Optional
+  * A list of other KEPs that are relevant to this KEP.
+  * In the form `KEP-123`
+* **replaces** Optional
+  * A list of KEPs that this KEP replaces.  Those KEPs should list this KEP in
+    their `superceded-by`.
+  * In the form `KEP-123`
+* **superseded-by**
+  * A list of KEPs that superced this KEP. Use of this should be paired with
+    this KEP moving into the `Replaced` status.
+  * In the form `KEP-123`
+
+
 ### KEP Workflow
 
+TODO(jbeda) Rationalize this with status entires in the Metadata above.
+
 A KEP is proposed to have the following states
 
 - **opened**: a new KEP has been filed but not triaged by the responsible SIG or