diff options
| -rw-r--r-- | contributors/design-proposals/architecture/0000-kep-template.md | 189 | ||||
| -rw-r--r-- | contributors/design-proposals/architecture/1-kubernetes-enhancement-proposal-process.md (renamed from contributors/design-proposals/architecture/kubernetes-enhancement-proposal-process.md) | 157 | ||||
| -rw-r--r-- | contributors/design-proposals/architecture/kep-template-instructions.md | 128 |
3 files changed, 281 insertions, 193 deletions
diff --git a/contributors/design-proposals/architecture/0000-kep-template.md b/contributors/design-proposals/architecture/0000-kep-template.md index 59c8fb12..76d57fbd 100644 --- a/contributors/design-proposals/architecture/0000-kep-template.md +++ b/contributors/design-proposals/architecture/0000-kep-template.md @@ -1,46 +1,191 @@ -[//]: # ( thank you for creating a KEP! ) -[//]: # ( read the suggested section content: https://github.com/calebamiles/community/blob/propose-kep-template/contributors/design-proposals/architecture/kep-template-instructions.md ) -[//]: # ( replace `Title` with the KEP title ) -[//]: # ( replace section content with your amazing proposal ) -[//]: # ( KEP filename should match title, replace spaces with `- `) -[//]: # ( update table of contents before merge ) -[//]: # ( remove comments before merge ) -[//]: # ( profit ) - # 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 +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 +authors: + - name: Jane Doe + github: janedoe + email: janedoe@example.com +owning-sig: sig-xxx +participating-sigs: + - sig-aaa + - sig-bbb +reviewers: + - name: TBD + # - name: Alice Doe + # github: alicedoe + # email: alicedoe@example.com +approvers: + - name: TBD + # - name: Oscar Doe + # github: oscardoe + # email: oscardoe@example.com +editor: + name: TBD +creation-date: yyyy-mm-dd +last-updated: yyyy-mm-dd +status: draft +see-also: + - KEP-1 + - KEP-2 +replaces: + - KEP-3 +superseded-by: + - KEP-100 +``` + ## Table of Contents -- [Title](#title) - - [Metadata](#metadata) - - [Table of Contents](#table-of-contents) - - [Summary](#summary) - - [Motivation](#motivation) - - [Guide-level Explanation](#guide-level-explanation-optional) - - [Reference-level explanation](#reference-level-explanation) - - [Graduation Criteria](#graduation-criteria) - - [Implementation History](#implementation-history) - - [Drawbacks](#drawbacks-optional) - - [Alternatives](#alternatives-optional) - - [Unresolved Questions](#unresolved-questions-optional) - - [Mentors](#mentors-optional) +A table of contents is helpful for quickly jumping to sections of a KEP and for +highlighting any addtional information provided beyond the standard KEP +template. [Tools for generating][] a table of contents from markdown are +available. + +[Tools for generating]: https://github.com/ekalinin/github-markdown-toc ## Summary +The `Summary` section is incredibly important for producing high quality user +focused documentation such as release notes or a development road map. 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. + +A good summary is probably at least a paragraph in length. + ## Motivation +The `Motivation` section should describe + +- why we believe this change is important +- what benefits are expected to be realized from the change +- the high level design goals + +The `Motivation` section is important for getting all responsible parties to +understand the intention behind a change. 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 + ## Guide-level Explanation [optional] +Merging a change to source control is a crucial, but not final, milestone in +the implementation of a KEP. Enhancements need to be explained to the Kubernetes +community. The `Guide-level Explaination` section should be used to explain a +KEP to another Kubernaut after implementation. Excellent guidance can be +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 + + ## Reference-level explanation +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. + +Communicating dependencies across multiple SIGs is an important use for KEPs. +Explaining how a KEP interacts with other KEPs and existing Kubernetes +functionality should be included in this section. + +The `Reference-level explaination` section should ideally contain enough +information for someone besides the author to begin working on an implementation +of the KEP. In a similar manner to the guidance on [implementing an RFC][] from +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][] +instructions. + +[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 + ## Graduation Criteria +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. + +[umbrella issues]: https://github.com/kubernetes/kubernetes/issues/42752 + +## 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 SIG acceptance +- the `Detailed Design` 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 Kubneretes 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. + ## Unresolved Questions [optional] +The `Unresolved Questions` section is used to parking lot issues not ready to be +addressed before implementation begins. + ## Mentors [optional] + +Mentors who can help a community member implement a KEP which follows its +`Detailed Design` are crucial to scaling the Kubernetes project. Potential +mentors can list their contact information using their preferred contact +information in the `Mentors` section. diff --git a/contributors/design-proposals/architecture/kubernetes-enhancement-proposal-process.md b/contributors/design-proposals/architecture/1-kubernetes-enhancement-proposal-process.md index 12998578..ecea9a00 100644 --- a/contributors/design-proposals/architecture/kubernetes-enhancement-proposal-process.md +++ b/contributors/design-proposals/architecture/1-kubernetes-enhancement-proposal-process.md @@ -3,53 +3,50 @@ ## Metadata ``` --- -metadata: - number: 0001 - state: opened - authors: - - author: - name: caleb miles - github: @calebamiles - slack: @calebamiles - owners: - - sig-release - - sig-pm - - sig-architecture - - sig-testing - - steering-committee - links: - issues: - - [someIssueURL]() - prs: - - https://github.com/kubernetes/community/pull/967 - discussions: - - https://groups.google.com/forum/#!topic/kubernetes-dev/65A-3ULYPB0 - - https://groups.google.com/forum/#!topic/kubernetes-sig-architecture/t-1EqeEoLPA - documentation: - - [someDocsLinkURL]() - related: - - [KEP template](https://github.com/kubernetes/community/pull/1124) +kep-number: 1 +title: Kubernetes Enhancement Proposal Process +authors: + - name: Caleb Miles + github: calebamiles + slack: calebamiles + - name: Joe Beda + github: jbeda + email: joe@heptio.com + slack: jbeda +owning-sig: sig-architecture +participating-sigs: + - `kubernetes-wide` +reviewers: + - name: TBD +approvers: + - name: TBD +editor: + name: TBD +creation-date: 2017-08-22 +status: draft ``` ## Table of Contents -- [Kubernetes Enhancement Proposal Process](#kubernetes-enhancement-proposal-process) - - [Metadata](#metadata) - - [Summary](#summary) - - [Motivation](#motivation) - - [Reference-level explanation](#reference-level-explanation) - - [What type of work should be tracked by a KEP](#what-type-of-work-should-be-tracked-by-a-kep) - - [KEP Template](#kep-template) - - [KEP Workflow](#kep-workflow) - - [Git and GitHub Implementation](#git-and-github-implementation) - - [KEP Editor Role](#kep-editor-role) - - [Important Metrics](#important-metrics) - - [Prior Art](#prior-art) - - [Graduation Criteria](#graduation-criteria) - - [Drawbacks](#drawbacks) - - [Alternatives](#alternatives) - - [Unresolved Questions](#unresolved-questions) - - [Mentors](#mentors) +* [Kubernetes Enhancement Proposal Process](#kubernetes-enhancement-proposal-process) + * [Metadata](#metadata) + * [Table of Contents](#table-of-contents) + * [Summary](#summary) + * [Motivation](#motivation) + * [Reference-level explanation](#reference-level-explanation) + * [What type of work should be tracked by a KEP](#what-type-of-work-should-be-tracked-by-a-kep) + * [KEP Template](#kep-template) + * [KEP Metadata](#kep-metadata) + * [KEP Workflow](#kep-workflow) + * [Git and GitHub Implementation](#git-and-github-implementation) + * [KEP Editor Role](#kep-editor-role) + * [Important Metrics](#important-metrics) + * [Prior Art](#prior-art) + * [Graduation Criteria](#graduation-criteria) + * [Drawbacks](#drawbacks) + * [Alternatives](#alternatives) + * [Unresolved Questions](#unresolved-questions) + * [Mentors](#mentors) ## Summary @@ -158,8 +155,82 @@ The template for a KEP is precisely defined in the [template proposal][] [template proposal]: https://github.com/kubernetes/community/pull/1124 +### KEP Metadata + +There is a place in each KEP for a YAML document that has standard metadata. +This will be used to support tooling around filtering and display. It is also +critical to clearly communicate the status of a KEP. + +Metadata items: +* **kep-number** Required + * Each proposal has a number. This is to make all references to proposals as + clear as possible. This is especially important as we create a network + cross references between proposals. + * Before having the `Approved` status, the number for the KEP will be in the + form of `draft-YYYYMMDD`. The `YYYYMMDD` is replaced with the current date + when first creating the KEP. The goal is to enable fast parallel merges of + pre-acceptance KEPs. + * On acceptance a sequential dense number will be assigned. This will be done + by the editor and will be done in such a way as to minimize the chances of + conficts. The final number for a KEP will have no prefix. +* **title** Required + * The title of the KEP in plain language. The title will also be used in the + KEP filename. See the template for instructions and details. +* **status** Required + * The current state of the KEP. + * Must be one of `Draft`, `Deferred`, `Approved`, `Rejected`, `Withdrawn`, + `Final`, `Replaced`. +* **authors** Required + * A list of authors for the KEP. We require a name (which can be a psuedonym) + along with a github ID. Other ways to contact the author is strongly + encouraged. This is a list of maps. Subkeys of each item: `name`, + `github`, `email` (optional), `slack` (optional). +* **owning-sig** Required + * The SIG that is most closely associated with this KEP. If there is code or + other artifacts that will result from this KEP, then it is expected that + this SIG will take responsiblity for the bulk of those artificats. + * Sigs are listed as `sig-abc-def` where the name matches up with the + directory in the `kubernetes/community` repo. +* **participating-sigs** Optional + * A list of SIGs that are involved or impacted by this KEP. + * A special value of `kubernetes-wide` will indicate that this KEP has impact + across the entire project. +* **reviewers** Required + * Reviewer(s) chosen after triage according to proposal process + * If not yet chosen replace with `TBD` + * Same name/contact scheme as `authors` +* **approvers** Required + * Approver(s) chosen after triage according to proposal process + * If not yet chosen replace with `TBD` + * Same name/contact scheme as `authors` +* **editor** Required + * Someone to keep things moving forward. + * If not yet chosen replace with `TBD` + * Same name/contact scheme as `authors` +* **creation-date** Required + * The date that the KEP was first submitted in a PR. + * In the form `yyyy-mm-dd` + * While this info will also be in source control, it is helpful to have the set of KEP files stand on their own. +* **last-updated** Optional + * The date that the KEP was last changed significantly. + * In the form `yyyy-mm-dd` +* **see-also** Optional + * A list of other KEPs that are relevant to this KEP. + * In the form `KEP-123` +* **replaces** Optional + * A list of KEPs that this KEP replaces. Those KEPs should list this KEP in + their `superceded-by`. + * In the form `KEP-123` +* **superseded-by** + * A list of KEPs that superced this KEP. Use of this should be paired with + this KEP moving into the `Replaced` status. + * In the form `KEP-123` + + ### KEP Workflow +TODO(jbeda) Rationalize this with status entires in the Metadata above. + A KEP is proposed to have the following states - **opened**: a new KEP has been filed but not triaged by the responsible SIG or diff --git a/contributors/design-proposals/architecture/kep-template-instructions.md b/contributors/design-proposals/architecture/kep-template-instructions.md deleted file mode 100644 index b34d88b4..00000000 --- a/contributors/design-proposals/architecture/kep-template-instructions.md +++ /dev/null @@ -1,128 +0,0 @@ -# Title - -`Title` should be replace with the name of the KEP which should also match the -filename. Substitute spaces with `-`. - -## Metadata - -The `Metadata` section is intended to support the creation of tooling around the -KEP process. The precise format for `Metadata` is described in the -[metadata proposal][]. - -[metadata proposal]: https://docs.google.com/document/d/1ynmBMuDuT7yGzRscObB1KtgJj8ljYq0I5q4oshrJUCs/edit# - -## Table of Contents - -A table of contents is helpful for quickly jumping to sections of a KEP and for -highlighting any addtional information provided beyond the standard KEP -template. [Tools for generating][] a table of contents from markdown are -available. - -[Tools for generating]: https://github.com/ekalinin/github-markdown-toc - -## Summary - -The `Summary` section is incredibly important for producing high quality user -focused documentation such as release notes or a development road map. 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. - -A good summary is probably at least a paragraph in length. - -## Motivation - -The `Motivation` section should describe - -- why we believe this change is important -- what benefits are expected to be realized from the change -- the high level design goals - -The `Motivation` section is important for getting all responsible parties to -understand the intention behind a change. 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 - -## Guide-level Explanation [optional] - -Merging a change to source control is a crucial, but not final, milestone in -the implementation of a KEP. Enhancements need to be explained to the Kubernetes -community. The `Guide-level Explaination` section should be used to explain a -KEP to another Kubernaut after implementation. Excellent guidance can be -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 - - -## Reference-level explanation - -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. - -Communicating dependencies across multiple SIGs is an important use for KEPs. -Explaining how a KEP interacts with other KEPs and existing Kubernetes -functionality should be included in this section. - -The `Reference-level explaination` section should ideally contain enough -information for someone besides the author to begin working on an implementation -of the KEP. In a similar manner to the guidance on [implementing an RFC][] from -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][] -instructions. - -[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 - -## Graduation Criteria - -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. - -[umbrella issues]: https://github.com/kubernetes/kubernetes/issues/42752 - -## 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 SIG acceptance -- the `Detailed Design` 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 Kubneretes 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. - -## Unresolved Questions [optional] - -The `Unresolved Questions` section is used to parking lot issues not ready to be -addressed before implementation begins. - -## Mentors [optional] - -Mentors who can help a community member implement a KEP which follows its -`Detailed Design` are crucial to scaling the Kubernetes project. Potential -mentors can list their contact information using their preferred contact -information in the `Mentors` section. |