|
1 | | ---- |
2 | | -kep-number: 0 |
3 | | -title: My First KEP |
4 | | -authors: |
5 | | - - "@janedoe" |
6 | | -owning-sig: sig-xxx |
7 | | -participating-sigs: |
8 | | - - sig-aaa |
9 | | - - sig-bbb |
10 | | -reviewers: |
11 | | - - TBD |
12 | | - - "@alicedoe" |
13 | | -approvers: |
14 | | - - TBD |
15 | | - - "@oscardoe" |
16 | | -editor: TBD |
17 | | -creation-date: yyyy-mm-dd |
18 | | -last-updated: yyyy-mm-dd |
19 | | -status: provisional |
20 | | -see-also: |
21 | | - - KEP-1 |
22 | | - - KEP-2 |
23 | | -replaces: |
24 | | - - KEP-3 |
25 | | -superseded-by: |
26 | | - - KEP-100 |
27 | | ---- |
28 | | - |
29 | | -# Title |
30 | | - |
31 | | -This is the title of the KEP. |
32 | | -Keep it simple and descriptive. |
33 | | -A good title can help communicate what the KEP is and should be considered as part of any review. |
34 | | - |
35 | | -The *filename* for the KEP should include the KEP number along with the title. |
36 | | -The title should be lowercased and spaces/punctuation should be replaced with `-`. |
37 | | -As the KEP is approved and an official KEP number is allocated, the file should be renamed. |
38 | | - |
39 | | -To get started with this template: |
40 | | -1. **Pick a hosting SIG.** |
41 | | - Make sure that the problem space is something the SIG is interested in taking up. |
42 | | - KEPs should not be checked in without a sponsoring SIG. |
43 | | -1. **Allocate a KEP number.** |
44 | | - Do this by (a) taking the next number in the `NEXT_KEP_NUMBER` file and (b) incrementing that number. |
45 | | - Include the updated `NEXT_KEP_NUMBER` file in your PR. |
46 | | -1. **Make a copy of this template.** |
47 | | - Name it `NNNN-YYYYMMDD-my-title.md` where `NNNN` is the KEP number that was allocated. |
48 | | -1. **Fill out the "overview" sections.** |
49 | | - This includes the Summary and Motivation sections. |
50 | | - These should be easy if you've preflighted the idea of the KEP with the appropriate SIG. |
51 | | -1. **Create a PR.** |
52 | | - Assign it to folks in the SIG that are sponsoring this process. |
53 | | -1. **Merge early.** |
54 | | - Avoid getting hung up on specific details and instead aim to get the goal of the KEP merged quickly. |
55 | | - The best way to do this is to just start with the "Overview" sections and fill out details incrementally in follow on PRs. |
56 | | - View anything marked as a `provisional` as a working document and subject to change. |
57 | | - Aim for single topic PRs to keep discussions focused. |
58 | | - If you disagree with what is already in a document, open a new PR with suggested changes. |
59 | | - |
60 | | -The canonical place for the latest set of instructions (and the likely source of this file) is [here](/keps/0000-kep-template.md). |
61 | | - |
62 | | -The `Metadata` section above is intended to support the creation of tooling around the KEP process. |
63 | | -This will be a YAML section that is fenced as a code block. |
64 | | -See the KEP process for details on each of these items. |
65 | | - |
66 | | -## Table of Contents |
67 | | - |
68 | | -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. |
69 | | -[Tools for generating][] a table of contents from markdown are available. |
70 | | - |
71 | | -* [Table of Contents](#table-of-contents) |
72 | | -* [Summary](#summary) |
73 | | -* [Motivation](#motivation) |
74 | | - * [Goals](#goals) |
75 | | - * [Non-Goals](#non-goals) |
76 | | -* [Proposal](#proposal) |
77 | | - * [User Stories [optional]](#user-stories-optional) |
78 | | - * [Story 1](#story-1) |
79 | | - * [Story 2](#story-2) |
80 | | - * [Implementation Details/Notes/Constraints [optional]](#implementation-detailsnotesconstraints-optional) |
81 | | - * [Risks and Mitigations](#risks-and-mitigations) |
82 | | -* [Graduation Criteria](#graduation-criteria) |
83 | | -* [Implementation History](#implementation-history) |
84 | | -* [Drawbacks [optional]](#drawbacks-optional) |
85 | | -* [Alternatives [optional]](#alternatives-optional) |
86 | | - |
87 | | -[Tools for generating]: https://github.com/ekalinin/github-markdown-toc |
88 | | - |
89 | | -## Summary |
90 | | - |
91 | | -The `Summary` section is incredibly important for producing high quality user focused documentation such as release notes or a development road map. |
92 | | -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. |
93 | | -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. |
94 | | - |
95 | | -A good summary is probably at least a paragraph in length. |
96 | | - |
97 | | -## Motivation |
98 | | - |
99 | | -This section is for explicitly listing the motivation, goals and non-goals of this KEP. |
100 | | -Describe why the change is important and the benefits to users. |
101 | | -The motivation section can optionally provide links to [experience reports][] to demonstrate the interest in a KEP within the wider Kubernetes community. |
102 | | - |
103 | | -[experience reports]: https://github.com/golang/go/wiki/ExperienceReports |
104 | | - |
105 | | -### Goals |
106 | | - |
107 | | -List the specific goals of the KEP. |
108 | | -How will we know that this has succeeded? |
109 | | - |
110 | | -### Non-Goals |
111 | | - |
112 | | -What is out of scope for his KEP? |
113 | | -Listing non-goals helps to focus discussion and make progress. |
114 | | - |
115 | | -## Proposal |
116 | | - |
117 | | -This is where we get down to the nitty gritty of what the proposal actually is. |
118 | | - |
119 | | -### User Stories [optional] |
120 | | - |
121 | | -Detail the things that people will be able to do if this KEP is implemented. |
122 | | -Include as much detail as possible so that people can understand the "how" of the system. |
123 | | -The goal here is to make this feel real for users without getting bogged down. |
124 | | - |
125 | | -#### Story 1 |
126 | | - |
127 | | -#### Story 2 |
128 | | - |
129 | | -### Implementation Details/Notes/Constraints [optional] |
130 | | - |
131 | | -What are the caveats to the implementation? |
132 | | -What are some important details that didn't come across above. |
133 | | -Go in to as much detail as necessary here. |
134 | | -This might be a good place to talk about core concepts and how they releate. |
135 | | - |
136 | | -### Risks and Mitigations |
137 | | - |
138 | | -What are the risks of this proposal and how do we mitigate. |
139 | | -Think broadly. |
140 | | -For example, consider both security and how this will impact the larger kubernetes ecosystem. |
141 | | - |
142 | | -## Graduation Criteria |
143 | | - |
144 | | -How will we know that this has succeeded? |
145 | | -Gathering user feedback is crucial for building high quality experiences and SIGs have the important responsibility of setting milestones for stability and completeness. |
146 | | -Hopefully the content previously contained in [umbrella issues][] will be tracked in the `Graduation Criteria` section. |
147 | | - |
148 | | -[umbrella issues]: https://github.com/kubernetes/kubernetes/issues/42752 |
149 | | - |
150 | | -## Implementation History |
151 | | - |
152 | | -Major milestones in the life cycle of a KEP should be tracked in `Implementation History`. |
153 | | -Major milestones might include |
154 | | - |
155 | | -- the `Summary` and `Motivation` sections being merged signaling SIG acceptance |
156 | | -- the `Proposal` section being merged signaling agreement on a proposed design |
157 | | -- the date implementation started |
158 | | -- the first Kubernetes release where an initial version of the KEP was available |
159 | | -- the version of Kubernetes where the KEP graduated to general availability |
160 | | -- when the KEP was retired or superseded |
161 | | - |
162 | | -## Drawbacks [optional] |
163 | | - |
164 | | -Why should this KEP _not_ be implemented. |
165 | | - |
166 | | -## Alternatives [optional] |
167 | | - |
168 | | -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. |
169 | | - |
170 | | -## Infrastructure Needed [optional] |
171 | | - |
172 | | -Use this section if you need things from the project/SIG. |
173 | | -Examples include a new subproject, repos requested, github details. |
174 | | -Listing these here allows a SIG to get the process for these resources started right away. |
| 1 | +KEPs have moved to https://git.k8s.io/enhancements/. |
| 2 | +<!-- |
| 3 | +This file is a placeholder to preserve links. Please remove after 6 months or the release of Kubernetes 1.15, whichever comes first. |
| 4 | +--> |
0 commit comments