|
| 1 | +# Title |
| 2 | + |
| 3 | +`Title` should be replace with the name of the KEP which should also match the |
| 4 | +filename. Substitute spaces with `-`. |
| 5 | + |
| 6 | +## Metadata |
| 7 | + |
| 8 | +The `Metadata` section is intended to support the creation of tooling around the |
| 9 | +KEP process. The precise format for `Metadata` is described in the |
| 10 | +[metadata proposal][]. |
| 11 | + |
| 12 | +[metadata proposal]: https://docs.google.com/document/d/1ynmBMuDuT7yGzRscObB1KtgJj8ljYq0I5q4oshrJUCs/edit# |
| 13 | + |
| 14 | +## Table of Contents |
| 15 | + |
| 16 | +A table of contents is helpful for quickly jumping to sections of a KEP and for |
| 17 | +highlighting any addtional information provided beyond the standard KEP |
| 18 | +template. [Tools for generating][] a table of contents from markdown are |
| 19 | +available. |
| 20 | + |
| 21 | +[Tools for generating]: https://github.com/ekalinin/github-markdown-toc |
| 22 | + |
| 23 | +## Summary |
| 24 | + |
| 25 | +The `Summary` section is incredibly important for producing high quality user |
| 26 | +focused documentation such as release notes or a development road map. It should |
| 27 | +be possible to collect this information before implementation begins in order |
| 28 | +to avoid requiring implementors to split their attention between writing |
| 29 | +release notes and implementing the feature itself. KEP editors, SIG Docs, and |
| 30 | +SIG PM should help to ensure that the tone and content of the `Summary` section |
| 31 | +is useful for a wide audience. |
| 32 | + |
| 33 | +A good summary is probably at least a paragraph in length. |
| 34 | + |
| 35 | +## Motivation |
| 36 | + |
| 37 | +The `Motivation` section should describe |
| 38 | + |
| 39 | +- why we believe this change is important |
| 40 | +- what benefits are expected to be realized from the change |
| 41 | +- the high level design goals |
| 42 | + |
| 43 | +The `Motivation` section is important for getting all responsible parties to |
| 44 | +understand the intention behind a change. The motivation section can optionally |
| 45 | +provide links to [experience reports][] to demonstrate the interest in a KEP |
| 46 | +within the wider Kubernetes community. |
| 47 | + |
| 48 | +[experience reports]: https://github.com/golang/go/wiki/ExperienceReports |
| 49 | + |
| 50 | +## Guide-level Explanation [optional] |
| 51 | + |
| 52 | +Merging a change to source control is a crucial, but not final, milestone in |
| 53 | +the implementation of a KEP. Enhancements need to be explained to the Kubernetes |
| 54 | +community. The `Guide-level Explaination` section should be used to explain a |
| 55 | +KEP to another Kubernaut after implementation. Excellent guidance can be |
| 56 | +found in the Rust RFC [guide-level explanation][] instructions. |
| 57 | + |
| 58 | + |
| 59 | +[guide-level explanation]: https://github.com/rust-lang/rfcs/blob/master/0000-template.md#guide-level-explanation |
| 60 | + |
| 61 | + |
| 62 | +## Reference-level explanation |
| 63 | + |
| 64 | +Before submitting a detailed implementation plan, a KEP author might begin the |
| 65 | +`Reference-level Explaination` by sketching high level design goals and any |
| 66 | +mandatory requirements. |
| 67 | + |
| 68 | +Communicating dependencies across multiple SIGs is an important use for KEPs. |
| 69 | +Explaining how a KEP interacts with other KEPs and existing Kubernetes |
| 70 | +functionality should be included in this section. |
| 71 | + |
| 72 | +The `Reference-level explaination` section should ideally contain enough |
| 73 | +information for someone besides the author to begin working on an implementation |
| 74 | +of the KEP. In a similar manner to the guidance on [implementing an RFC][] from |
| 75 | +the Rust community, not all KEPs must be implemented immediately. Associating |
| 76 | +each KEP with one or more issues filed against Kubernetes repositories allows |
| 77 | +interested community members to track implementation. |
| 78 | + |
| 79 | +Excellent guidance can be found in the Rust RFC [reference-level explanation][] |
| 80 | +instructions. |
| 81 | + |
| 82 | +[reference-level explaination]: https://github.com/rust-lang/rfcs/blob/master/0000-template.md#reference-level-explanation |
| 83 | + |
| 84 | +[implementing an RFC]: https://github.com/rust-lang/rfcs/blob/master/README.md#implementing-an-rfc |
| 85 | + |
| 86 | +## Graduation Criteria |
| 87 | + |
| 88 | +Gathering user feedback is crucial for building high quality experiences and |
| 89 | +SIGs have the important responsibility of setting milestones for stability |
| 90 | +and completeness. Hopefully the content previously contained in |
| 91 | +[umbrella issues][] will be tracked in the `Graduation Criteria` section. |
| 92 | + |
| 93 | +[umbrella issues]: https://github.com/kubernetes/kubernetes/issues/42752 |
| 94 | + |
| 95 | +## Implementation History |
| 96 | + |
| 97 | +Major milestones in the life cycle of a KEP should be tracked in |
| 98 | +`Implementation History`. Major milestones might include |
| 99 | + |
| 100 | +- the `Summary` and `Motivation` sections being merged signaling SIG acceptance |
| 101 | +- the `Detailed Design` section being merged signaling agreement on a proposed |
| 102 | + design |
| 103 | +- the date implementation started |
| 104 | +- the first Kubernetes release where an initial version of the KEP was available |
| 105 | +- the version of Kubneretes where the KEP graduated to general availability |
| 106 | +- when the KEP was retired or superseded |
| 107 | + |
| 108 | +## Drawbacks [optional] |
| 109 | + |
| 110 | +Why should this KEP _not_ be implemented. |
| 111 | + |
| 112 | +## Alternatives [optional] |
| 113 | + |
| 114 | +Similar to the `Drawbacks` section the `Alternatives` section is used to |
| 115 | +highlight and record other possible approaches to delivering the value proposed |
| 116 | +by a KEP. |
| 117 | + |
| 118 | +## Unresolved Questions [optional] |
| 119 | + |
| 120 | +The `Unresolved Questions` section is used to parking lot issues not ready to be |
| 121 | +addressed before implementation begins. |
| 122 | + |
| 123 | +## Mentors [optional] |
| 124 | + |
| 125 | +Mentors who can help a community member implement a KEP which follows its |
| 126 | +`Detailed Design` are crucial to scaling the Kubernetes project. Potential |
| 127 | +mentors can list their contact information using their preferred contact |
| 128 | +information in the `Mentors` section. |
0 commit comments