183 lines
7 KiB
Markdown
183 lines
7 KiB
Markdown
|
---
|
||
|
|
title: KEP Template
|
||
|
|
authors:
|
||
|
|
- "@janedoe"
|
||
|
|
reviewers:
|
||
|
|
- TBD
|
||
|
|
- "@alicedoe"
|
||
|
|
approvers:
|
||
|
|
- TBD
|
||
|
|
- "@oscardoe"
|
||
|
|
editor: TBD
|
||
|
|
creation-date: yyyy-mm-dd
|
||
|
|
last-updated: yyyy-mm-dd
|
||
|
|
status: provisional|implementable|implemented|deferred|rejected|withdrawn|replaced
|
||
|
|
see-also:
|
||
|
|
- "/docs/enhancements/20190101-we-heard-you-like-keps.md"
|
||
|
|
- "/docs/enhancements/20190102-everyone-gets-a-kep.md"
|
||
|
|
replaces:
|
||
|
|
- "/docs/enhancements/20181231-replaced-kep.md"
|
||
|
|
superseded-by:
|
||
|
|
- "/docs/enhancements/20190104-superceding-kep.md"
|
||
|
|
---
|
||
|
|
|
||
|
|
# 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 title should be lowercased and spaces/punctuation should be replaced with `-`.
|
||
|
|
|
||
|
|
To get started with this template:
|
||
|
|
|
||
|
|
1. **Make a copy of this template.**
|
||
|
|
Create a copy of this template 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 in an issue.
|
||
|
|
1. **Create a PR.**
|
||
|
|
Assign it to folks that are sponsoring this process.
|
||
|
|
1. **Create an issue**
|
||
|
|
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.
|
||
|
|
View anything marked as a `provisional` as a working document and subject to change.
|
||
|
|
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.
|
||
|
|
|
||
|
|
The canonical place for the latest set of instructions (and the likely source of this file) is [here](/keps/YYYYMMDD-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.
|
||
|
|
|
||
|
|
Ensure the TOC is wrapped with <code><!-- toc --&rt;<!-- /toc --&rt;</code> tags, and then generate with `hack/update-toc.sh`.
|
||
|
|
|
||
|
|
<!-- toc -->
|
||
|
|
- [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)
|
||
|
|
- [Removing a deprecated flag](#removing-a-deprecated-flag)
|
||
|
|
- [Implementation History](#implementation-history)
|
||
|
|
- [Drawbacks [optional]](#drawbacks-optional)
|
||
|
|
- [Alternatives [optional]](#alternatives-optional)
|
||
|
|
<!-- /toc -->
|
||
|
|
|
||
|
|
## Summary
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
A good summary is probably at least a paragraph in length.
|
||
|
|
|
||
|
|
## Motivation
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
[experience reports]: https://github.com/golang/go/wiki/ExperienceReports
|
||
|
|
|
||
|
|
### Goals
|
||
|
|
|
||
|
|
List the specific goals of the KEP.
|
||
|
|
How will we know that this has succeeded?
|
||
|
|
|
||
|
|
### Non-Goals
|
||
|
|
|
||
|
|
What is out of scope for this KEP?
|
||
|
|
Listing non-goals helps to focus discussion and make progress.
|
||
|
|
|
||
|
|
## Proposal
|
||
|
|
|
||
|
|
This is where we get down to the nitty gritty of what the proposal actually is.
|
||
|
|
|
||
|
|
### User Stories [optional]
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
#### Story 1
|
||
|
|
|
||
|
|
#### Story 2
|
||
|
|
|
||
|
|
### Implementation Details/Notes/Constraints [optional]
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
### Risks and Mitigations
|
||
|
|
|
||
|
|
What are the risks of this proposal and how do we mitigate.
|
||
|
|
Think broadly.
|
||
|
|
For example, consider both security and how this will impact the larger kubernetes ecosystem.
|
||
|
|
|
||
|
|
How will security be reviewed and by whom?
|
||
|
|
How will UX be reviewed and by whom?
|
||
|
|
|
||
|
|
Consider including folks that also work outside project.
|
||
|
|
|
||
|
|
## Design Details
|
||
|
|
|
||
|
|
### Test Plan
|
||
|
|
|
||
|
|
**Note:** *Section not required until targeted at a release.*
|
||
|
|
|
||
|
|
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
|
||
|
|
|
||
|
|
#### Removing a deprecated flag
|
||
|
|
|
||
|
|
- 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
|
||
|
|
|
||
|
|
## 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 acceptance
|
||
|
|
- 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
|
||
|
|
- 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.
|