KEP template: Move metadata to front.
Also move to line per sentence for better diffs for later editing. Signed-off-by: Joe Beda <joe.github@bedafamily.com>
This commit is contained in:
parent
76f2ea4795
commit
c5abc490f9
|
@ -1,67 +1,19 @@
|
||||||
# Title
|
---
|
||||||
|
kep-number: draft-YYYYMMDD
|
||||||
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
|
title: My First KEP
|
||||||
authors:
|
authors:
|
||||||
- name: Jane Doe
|
- "@janedoe"
|
||||||
github: janedoe
|
|
||||||
email: janedoe@example.com
|
|
||||||
owning-sig: sig-xxx
|
owning-sig: sig-xxx
|
||||||
participating-sigs:
|
participating-sigs:
|
||||||
- sig-aaa
|
- sig-aaa
|
||||||
- sig-bbb
|
- sig-bbb
|
||||||
reviewers:
|
reviewers:
|
||||||
- name: TBD
|
- TBD
|
||||||
# - name: Alice Doe
|
- "@alicedoe"
|
||||||
# github: alicedoe
|
|
||||||
# email: alicedoe@example.com
|
|
||||||
approvers:
|
approvers:
|
||||||
- name: TBD
|
- TBD
|
||||||
# - name: Oscar Doe
|
- "@oscardoe"
|
||||||
# github: oscardoe
|
editor: TBD
|
||||||
# email: oscardoe@example.com
|
|
||||||
editor:
|
|
||||||
name: TBD
|
|
||||||
creation-date: yyyy-mm-dd
|
creation-date: yyyy-mm-dd
|
||||||
last-updated: yyyy-mm-dd
|
last-updated: yyyy-mm-dd
|
||||||
status: draft
|
status: draft
|
||||||
|
@ -72,26 +24,51 @@ replaces:
|
||||||
- KEP-3
|
- KEP-3
|
||||||
superseded-by:
|
superseded-by:
|
||||||
- KEP-100
|
- KEP-100
|
||||||
```
|
---
|
||||||
|
|
||||||
|
# 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 (remove this)
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
## Table of Contents
|
## Table of Contents
|
||||||
|
|
||||||
A table of contents is helpful for quickly jumping to sections of a KEP and for
|
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.
|
||||||
highlighting any additional information provided beyond the standard KEP
|
[Tools for generating][] a table of contents from markdown are available.
|
||||||
template. [Tools for generating][] a table of contents from markdown are
|
|
||||||
available.
|
|
||||||
|
|
||||||
[Tools for generating]: https://github.com/ekalinin/github-markdown-toc
|
[Tools for generating]: https://github.com/ekalinin/github-markdown-toc
|
||||||
|
|
||||||
## Summary
|
## Summary
|
||||||
|
|
||||||
The `Summary` section is incredibly important for producing high quality user
|
The `Summary` section is incredibly important for producing high quality user focused documentation such as release notes or a development road map.
|
||||||
focused documentation such as release notes or a development road map. It should
|
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.
|
||||||
be possible to collect this information before implementation begins in order
|
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.
|
||||||
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.
|
A good summary is probably at least a paragraph in length.
|
||||||
|
|
||||||
|
@ -103,66 +80,50 @@ The `Motivation` section should describe
|
||||||
- what benefits are expected to be realized from the change
|
- what benefits are expected to be realized from the change
|
||||||
- the high level design goals
|
- the high level design goals
|
||||||
|
|
||||||
The `Motivation` section is important for getting all responsible parties to
|
The `Motivation` section is important for getting all responsible parties to understand the intention behind a change.
|
||||||
understand the intention behind a change. The motivation section can optionally
|
The motivation section can optionally provide links to [experience reports][] to demonstrate the interest in a KEP within the wider Kubernetes community.
|
||||||
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
|
[experience reports]: https://github.com/golang/go/wiki/ExperienceReports
|
||||||
|
|
||||||
## Guide-level Explanation [optional]
|
## Guide-level Explanation [optional]
|
||||||
|
|
||||||
Merging a change to source control is a crucial, but not final, milestone in
|
Merging a change to source control is a crucial, but not final, milestone in the implementation of a KEP.
|
||||||
the implementation of a KEP. Enhancements need to be explained to the Kubernetes
|
Enhancements need to be explained to the Kubernetes community.
|
||||||
community. The `Guide-level Explaination` section should be used to explain a
|
The `Guide-level Explaination` section should be used to explain a KEP to another Kubernaut after implementation.
|
||||||
KEP to another Kubernaut after implementation. Excellent guidance can be
|
Excellent guidance can be found in the Rust RFC [guide-level explanation][] instructions.
|
||||||
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
|
[guide-level explanation]: https://github.com/rust-lang/rfcs/blob/master/0000-template.md#guide-level-explanation
|
||||||
|
|
||||||
|
|
||||||
## Reference-level explanation
|
## Reference-level explanation
|
||||||
|
|
||||||
Before submitting a detailed implementation plan, a KEP author might begin the
|
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.
|
||||||
`Reference-level Explaination` by sketching high level design goals and any
|
|
||||||
mandatory requirements.
|
|
||||||
|
|
||||||
Communicating dependencies across multiple SIGs is an important use for KEPs.
|
Communicating dependencies across multiple SIGs is an important use for KEPs.
|
||||||
Explaining how a KEP interacts with other KEPs and existing Kubernetes
|
Explaining how a KEP interacts with other KEPs and existing Kubernetes functionality should be included in this section.
|
||||||
functionality should be included in this section.
|
|
||||||
|
|
||||||
The `Reference-level explaination` section should ideally contain enough
|
The `Reference-level explaination` section should ideally contain enough information for someone besides the author to begin working on an implementation of the KEP.
|
||||||
information for someone besides the author to begin working on an implementation
|
In a similar manner to the guidance on [implementing an RFC][] from the Rust community, not all KEPs must be implemented immediately.
|
||||||
of the KEP. In a similar manner to the guidance on [implementing an RFC][] from
|
Associating each KEP with one or more issues filed against Kubernetes repositories allows interested community members to track implementation.
|
||||||
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][]
|
Excellent guidance can be found in the Rust RFC [reference-level explanation][] instructions.
|
||||||
instructions.
|
|
||||||
|
|
||||||
[reference-level explaination]: https://github.com/rust-lang/rfcs/blob/master/0000-template.md#reference-level-explanation
|
[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
|
[implementing an RFC]: https://github.com/rust-lang/rfcs/blob/master/README.md#implementing-an-rfc
|
||||||
|
|
||||||
## Graduation Criteria
|
## Graduation Criteria
|
||||||
|
|
||||||
Gathering user feedback is crucial for building high quality experiences and
|
Gathering user feedback is crucial for building high quality experiences and SIGs have the important responsibility of setting milestones for stability and completeness.
|
||||||
SIGs have the important responsibility of setting milestones for stability
|
Hopefully the content previously contained in [umbrella issues][] will be tracked in the `Graduation Criteria` section.
|
||||||
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
|
[umbrella issues]: https://github.com/kubernetes/kubernetes/issues/42752
|
||||||
|
|
||||||
## Implementation History
|
## Implementation History
|
||||||
|
|
||||||
Major milestones in the life cycle of a KEP should be tracked in
|
Major milestones in the life cycle of a KEP should be tracked in `Implementation History`.
|
||||||
`Implementation History`. Major milestones might include
|
Major milestones might include
|
||||||
|
|
||||||
- the `Summary` and `Motivation` sections being merged signaling SIG acceptance
|
- the `Summary` and `Motivation` sections being merged signaling SIG acceptance
|
||||||
- the `Detailed Design` section being merged signaling agreement on a proposed
|
- the `Detailed Design` section being merged signaling agreement on a proposed design
|
||||||
design
|
|
||||||
- the date implementation started
|
- the date implementation started
|
||||||
- the first Kubernetes release where an initial version of the KEP was available
|
- the first Kubernetes release where an initial version of the KEP was available
|
||||||
- the version of Kubernetes where the KEP graduated to general availability
|
- the version of Kubernetes where the KEP graduated to general availability
|
||||||
|
@ -174,18 +135,13 @@ Why should this KEP _not_ be implemented.
|
||||||
|
|
||||||
## Alternatives [optional]
|
## Alternatives [optional]
|
||||||
|
|
||||||
Similar to the `Drawbacks` section the `Alternatives` section is used to
|
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.
|
||||||
highlight and record other possible approaches to delivering the value proposed
|
|
||||||
by a KEP.
|
|
||||||
|
|
||||||
## Unresolved Questions [optional]
|
## Unresolved Questions [optional]
|
||||||
|
|
||||||
The `Unresolved Questions` section is used to parking lot issues not ready to be
|
The `Unresolved Questions` section is used to parking lot issues not ready to be addressed before implementation begins.
|
||||||
addressed before implementation begins.
|
|
||||||
|
|
||||||
## Mentors [optional]
|
## Mentors [optional]
|
||||||
|
|
||||||
Mentors who can help a community member implement a KEP which follows its
|
Mentors who can help a community member implement a KEP which follows its `Detailed Design` are crucial to scaling the Kubernetes project.
|
||||||
`Detailed Design` are crucial to scaling the Kubernetes project. Potential
|
Potential mentors can list their contact information using their preferred contact information in the `Mentors` section.
|
||||||
mentors can list their contact information using their preferred contact
|
|
||||||
information in the `Mentors` section.
|
|
||||||
|
|
Loading…
Reference in New Issue