Additional KEP template updates

justaugustus · justaugustus · commit c727437947f5 · 2019-02-08T13:37:16.000-05:00
Signed-off-by: Stephen Augustus &lt;saugustus@vmware.com&gt;
diff --git a/keps/0000-kep-template.md b/keps/0000-kep-template.md
@@ -1,6 +1,5 @@
 ---
-kep-number: 0
-title: My First KEP
+title: KEP Template
 authors:
   - "@janedoe"
 owning-sig: sig-xxx
@@ -16,14 +15,14 @@ approvers:
 editor: TBD
 creation-date: yyyy-mm-dd
 last-updated: yyyy-mm-dd
-status: provisional
+status: provisional|implementable|implemented|deferred|rejected|withdrawn|replaced
 see-also:
-  - KEP-1
-  - KEP-2
+  - "/keps/sig-aaa/20190101-we-heard-you-like-keps.md"
+  - "/keps/sig-bbb/20190102-everyone-gets-a-kep.md"
 replaces:
-  - KEP-3
+  - "/keps/sig-ccc/20181231-replaced-kep.md"
 superseded-by:
-  - KEP-100
+  - "/keps/sig-xxx/20190104-superceding-kep.md"
 ---
 
 # Title
@@ -39,12 +38,14 @@ To get started with this template:
   Make sure that the problem space is something the SIG is interested in taking up.
   KEPs should not be checked in without a sponsoring SIG.
 1. **Make a copy of this template.**
-  Name it `YYYYMMDD-my-title.md`.
+  Copy this template into the owning SIG's directory (or KEP root directory, as appropriate) and name it `YYYYMMDD-my-title.md`, where `YYYYMMDD` is the date the KEP was first drafted.
 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. **Create an issue in kubernetes/enhancements, if the enhancement will be targeting changes to kubernetes/kubernetes**
+  When filing an enhancement tracking issue, please ensure to complete all fields in the template.
 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.
@@ -63,44 +64,65 @@ See the KEP process for details on each of these items.
 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)
-    * [Risks and Mitigations](#risks-and-mitigations)
-* [Graduation Criteria](#graduation-criteria)
-* [Implementation History](#implementation-history)
-* [Drawbacks [optional]](#drawbacks-optional)
-* [Alternatives [optional]](#alternatives-optional)
-* [Infrastructure Needed [optional]](#infrastructure-needed-optional)
+- [Title](#title)
+  - [Table of Contents](#table-of-contents)
+  - [Release Signoff Checklist](#release-signoff-checklist)
+  - [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)
+    - [Risks and Mitigations](#risks-and-mitigations)
+  - [Design Details](#design-details)
+    - [Test Plan](#test-plan)
+    - [Graduation Criteria](#graduation-criteria)
+      - [Examples](#examples)
+        - [Alpha -> Beta Graduation](#alpha---beta-graduation)
+        - [Beta -> GA Graduation](#beta---ga-graduation)
+        - [Removing a deprecated flag](#removing-a-deprecated-flag)
+    - [Upgrade / Downgrade Strategy](#upgrade--downgrade-strategy)
+    - [Version Skew Strategy](#version-skew-strategy)
+  - [Implementation History](#implementation-history)
+  - [Drawbacks [optional]](#drawbacks-optional)
+  - [Alternatives [optional]](#alternatives-optional)
+  - [Infrastructure Needed [optional]](#infrastructure-needed-optional)
 
 [Tools for generating]: https://github.com/ekalinin/github-markdown-toc
 
-**ACTION REQUIRED (Seriously):** There must be an issue in [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes/issues)
-referencing this KEP and targeted a release milestone *before the [feature freeze](https://github.com/kubernetes/sig-release/tree/master/releases)
-of the targeted release*.
+## Release Signoff Checklist
 
-## Release Sign off Checklist
+**ACTION REQUIRED:** In order to merge code into a release, there must be an issue in [kubernetes/enhancements] referencing this KEP and targeting a release milestone **before [Enhancement Freeze](https://github.com/kubernetes/sig-release/tree/master/releases)
+of the targeted release**.
 
-Check these off as the are completed for the release team to track.  These must be updated for the feature to be
-released.
+For enhancements that make changes to code or processes/procedures in core Kubernetes i.e., [kubernetes/kubernetes], we require the following Release Signoff checklist to be completed.
 
-- [ ] Issue in release milestone linked to KEP (insert link here)
-- [ ] Design
-- [ ] Test Plan
-- [ ] Graduation Plan
-- [ ] Implemented
-- [ ] Documented
+Check these off as they are completed for the Release Team to track. These checklist items _must_ be updated for the enhancement to be released.
+
+- [ ] kubernetes/enhancements issue in release milestone, which links to KEP (this should be a link to the KEP location in kubernetes/enhancements, not the initial KEP PR)
+- [ ] KEP approvers have set the KEP status to `implementable`
+- [ ] Design details are appropriately documented
+- [ ] Test plan is in place, giving consideration to SIG Architecture and SIG Testing input
+- [ ] Graduation criteria is in place
+- [ ] "Implementation History" section is up-to-date for milestone
+- [ ] User-facing documentation has been created in [kubernetes/website], for publication to [kubernetes.io]
+- [ ] Supporting documentation e.g., additional design documents, links to mailing list discussions/SIG meetings, relevant PRs/issues, release notes
+
+**Note:** Any PRs to move a KEP to `implementable` or significant changes once it is marked `implementable` should be approved by each of the KEP approvers. If any of those approvers is no longer appropriate than changes to that list should be approved by the remaining approvers and/or the owning SIG (or SIG-arch for cross cutting KEPs).
+
+**Note:** This checklist is iterative and should be reviewed and updated every time this enhancement is being considered for a milestone.
+
+[kubernetes.io]: https://kubernetes.io/
+[kubernetes/enhancements]: https://github.com/kubernetes/enhancements/issues
+[kubernetes/kubernetes]: https://github.com/kubernetes/kubernetes
+[kubernetes/website]: https://github.com/kubernetes/website
 
 ## Summary
 
-The `Summary` section is incredibly important for producing high quality user focused documentation such as release notes or a development road map.
+The `Summary` section is incredibly important for producing high quality user-focused documentation such as release notes or a development roadmap.
 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.
 
@@ -121,7 +143,7 @@ How will we know that this has succeeded?
 
 ### Non-Goals
 
-What is out of scope for his KEP?
+What is out of scope for this KEP?
 Listing non-goals helps to focus discussion and make progress.
 
 ## Proposal
@@ -154,71 +176,94 @@ For example, consider both security and how this will impact the larger kubernet
 How will security be reviewed and by whom?
 How will UX be reviewed and by whom?
 
-Consider including folks that also work outside the sig or subproject.
+Consider including folks that also work outside the SIG or subproject.
 
 ## Design Details
 
 ### Test Plan
 
 **Note:** *Section not required until targeted at a release.*
 
-What is the test plan for the component?  E2e, integration, unit testing.  How will it be tested in isolation vs
-with other components?
+Consider the following in developing a test plan for this enhancement:
+- Will there be e2e and integration tests, in addition to unit tests?
+- How will it be tested in isolation vs with other components?
 
 No need to outline all of the test cases, just the general strategy.
+Anything that would count as tricky in the implementation and anything particularly challenging to test should be called out.
+
+All code is expected to have adequate tests (eventually with coverage expectations).
+Please adhere to the [Kubernetes testing guidelines][testing-guidelines] when drafting this test plan.
+
+[testing-guidelines]: https://git.k8s.io/community/contributors/devel/sig-testing/testing.md
 
 ### Graduation Criteria
 
 **Note:** *Section not required until targeted at a release.*
 
-Define graduation milestones. These may be defined in terms of API maturity, or as something else.  Initial KEP should keep
+Define graduation milestones.
+
+These may be defined in terms of API maturity, or as something else. Initial KEP should keep
 this high-level with a focus on what signals will be looked at to determine graduation.
 
+Consider the following in developing the graduation criteria for this enhancement:
+- [Maturity levels (`alpha`, `beta`, `stable`)][maturity-levels]
+- [Deprecation policy][deprecation-policy]
+
 Clearly define what graduation means by either linking to the [API doc definition](https://kubernetes.io/docs/concepts/overview/kubernetes-api/#api-versioning),
 or by redefining what graduation means.
 
-Example 1:
+In general, we try to use the same stages (alpha, beta, GA), regardless how the functionality is accessed.
+
+[maturity-levels]: https://git.k8s.io/community/contributors/devel/sig-architecture/api_changes.md#alpha-beta-and-stable-versions
+[deprecation-policy]: https://kubernetes.io/docs/reference/using-api/deprecation-policy/
 
-Alpha -> Beta Graduation:
+#### Examples
+
+These are generalized examples to consider, in addition to the aforementioned [maturity levels][maturity-levels].
+
+##### Alpha -> Beta Graduation
 
 - Gather feedback from developers and surveys
 - Complete features A, B, C
+- Tests are in Testgrid and linked in KEP
 
-Example 2:
-
-Beta -> GA Graduation:
+##### Beta -> GA Graduation
 
 - N examples of real world usage
 - N installs
-- Complete features D, E, F
-
-Example 3:
+- More rigorous forms of testing e.g., downgrade tests and scalability tests
+- Allowing time for feedback
 
-kubectl flag Opt-in -> Opt-out
+**Note:** Generally we also wait at least 2 releases between beta and GA/stable, since there's no opportunity for user feedback, or even bug reports, in back-to-back releases.
 
-- 2 versions passed since introducing flag (to address version skew)
-- Address feedback from opt-in usage provided on GitHub issues
+##### Removing a deprecated flag
 
-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.
+- Announce deprecation and support policy of the existing flag
+- Two versions passed since introducing the functionality which deprecates the flag (to address version skew)
+- Address feedback on usage/changed behavior, provided on GitHub issues
+- Deprecate the flag
 
-For non-optional features moving to GA, the graduation criteria must include [conformance tests](https://github.com/kubernetes/community/blob/master/contributors/devel/conformance-tests.md).
+**For non-optional features moving to GA, the graduation criteria must include [conformance tests].**
 
-[umbrella issues]: https://github.com/kubernetes/kubernetes/issues/42752
+[conformance tests]: https://github.com/kubernetes/community/blob/master/contributors/devel/conformance-tests.md
 
 ### Upgrade / Downgrade Strategy
 
-**Note:** *Section not required until targeted at a release.*
+If applicable, how will the component be upgraded and downgraded? Make sure this is in the test plan.
 
-If applicable, how will the component be upgraded and downgraded?  Make sure this is in the test plan.
+Consider the following in developing an upgrade/downgrade strategy for this enhancement:
+- What changes (in invocations, configurations, API use, etc.) is an existing cluster required to make on upgrade in order to keep previous behavior?
+- What changes (in invocations, configurations, API use, etc.) is an existing cluster required to make on upgrade in order to make use of the enhancement?
 
 ### Version Skew Strategy
 
-**Note:** *Section not required until targeted at a release.*
-
-If applicable, how will the component handle version skew with other components?  What are the guarantees?  Make sure
+If applicable, how will the component handle version skew with other components? What are the guarantees? Make sure
 this is in the test plan.
 
+Consider the following in developing a version skew strategy for this enhancement:
+- Does this enhancement involve coordinating behavior in the control plane and in the kubelet? How does an n-2 kubelet without this feature available behave when this feature is used?
+- Will any other components on the node change? For example, changes to CSI, CRI or CNI may require updating that component before the kubelet.
+
 ## Implementation History
 
 Major milestones in the life cycle of a KEP should be tracked in `Implementation History`.
