diff options
| author | Kubernetes Submit Queue <k8s-merge-robot@users.noreply.github.com> | 2017-12-19 11:28:39 -0800 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2017-12-19 11:28:39 -0800 |
| commit | 309b27fa953456080dc56babc8e051943fb652fe (patch) | |
| tree | cacfc2195e0dca668c51661aa6032ee6005971d3 /contributors | |
| parent | 3fd1ec027bab5b4a7c4daec77857e62574e2eb70 (diff) | |
| parent | ae099f58db46f6820c0172df59114d41a6402aa5 (diff) | |
Merge pull request #1531 from jbeda/kep-update
Automatic merge from submit-queue.
Move KEPs to top level directory
Diffstat (limited to 'contributors')
3 files changed, 2 insertions, 616 deletions
diff --git a/contributors/design-proposals/architecture/0000-kep-template.md b/contributors/design-proposals/architecture/0000-kep-template.md deleted file mode 100644 index 45783f8d..00000000 --- a/contributors/design-proposals/architecture/0000-kep-template.md +++ /dev/null @@ -1,158 +0,0 @@ ---- -kep-number: draft-YYYYMMDD -title: My First KEP -authors: - - "@janedoe" -owning-sig: sig-xxx -participating-sigs: - - sig-aaa - - sig-bbb -reviewers: - - TBD - - "@alicedoe" -approvers: - - TBD - - "@oscardoe" -editor: 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 ---- - -# 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). - -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. -[Tools for generating][] a table of contents from markdown are available. - - -* [Table of Contents](#table-of-contents) -* [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) - * [Security Considerations](#security-considerations) -* [Graduation Criteria](#graduation-criteria) -* [Implementation History](#implementation-history) -* [Drawbacks [optional]](#drawbacks-optional) -* [Alternatives [optional]](#alternatives-optional) - - -[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 - -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 his 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. - -### Security Considerations - -Make sure that you consider the impact of this feature from the point of view of Security. - -## Graduation Criteria - -How will we know that this has succeeded? -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 `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. diff --git a/contributors/design-proposals/architecture/1-kubernetes-enhancement-proposal-process.md b/contributors/design-proposals/architecture/1-kubernetes-enhancement-proposal-process.md deleted file mode 100644 index 5477a9b3..00000000 --- a/contributors/design-proposals/architecture/1-kubernetes-enhancement-proposal-process.md +++ /dev/null @@ -1,458 +0,0 @@ -# Kubernetes Enhancement Proposal Process - -## Metadata -``` ---- -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) - * [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 - -A standardized development process for Kubernetes is proposed in order to - -- provide a common structure for proposing changes to Kubernetes -- ensure that the motivation for a change is clear -- allow for the enumeration stability milestones and stability graduation - criteria -- persist project information in a Version Control System (VCS) for future - Kubernauts -- support the creation of _high value user facing_ information such as: - - an overall project development roadmap - - motivation for impactful user facing changes -- support development across multiple repositories beyond `kubernetes/kubernetes` -- reserve GitHub issues for tracking work in flight rather than creating "umbrella" - issues -- ensure community participants are successfully able to drive changes to - completion across one or more releases while stakeholders are adequately - represented throughout the process - -This process is supported by a unit of work called a Kubernetes Enhancement -Proposal or KEP. A KEP attempts to combine aspects of a - -- feature, and effort tracking document -- a product requirements document -- design document - -into one file which is created incrementally in collaboration with one or more -Special Interest Groups (SIGs). - -## Motivation - -For cross project SIGs such as SIG PM and SIG Release an abstraction beyond a -single GitHub Issue or Pull request seems to be required in order to understand -and communicate upcoming changes to Kubernetes. In a blog post describing the -[road to Go 2][], Russ Cox explains - -> that it is difficult but essential to describe the significance of a problem -> in a way that someone working in a different environment can understand - -as a project it is vital to be able to track the chain of custody for a proposed -enhancement from conception through implementation. This proposal does not -attempt to mandate how SIGs track their work internally, however, it is -suggested that SIGs which do not adhere to a process which allows for their hard -work to be explained to others in the wider Kubernetes community will see their -work wallow in the shadows of obscurity. At the very least [survey data][] -suggest that high quality documentation is crucial to project adoption. -Documentation can take many forms and it is imperative to ensure that it is easy -to produce high quality user or developer focused documentation for a complex -project like Kubernetes. - -Without a standardized mechanism for describing important enhancements our -talented technical writers and product managers struggle to weave a coherent -narrative explaining why a particular release is important. Additionally for -critical infrastructure such as Kubernetes adopters need a forward looking road -map in order to plan their adoption strategy. - -The purpose of the KEP process is to reduce the amount of "tribal knowledge" in -our community. By moving decisions from a smattering of mailing lists, video -calls and hallway conversations into a well tracked artifact this process aims -to enhance communication and discoverability. - -A KEP is broken into sections which can be merged into source control -incrementally in order to support an iterative development process. An important -goal of the KEP process is ensuring that the process for submitting the content -contained in [design proposals][] is both clear and efficient. The KEP process -is intended to create high quality uniform design and implementation documents -for SIGs to deliberate. - -[tell a story]: https://blog.rust-lang.org/2017/08/31/Rust-1.20.html -[road to Go 2]: https://blog.golang.org/toward-go2 -[survey data]: http://opensourcesurvey.org/2017/ -[design proposals]: https://github.com/kubernetes/community/tree/master/contributors/design-proposals - - -## Reference-level explanation - -### What type of work should be tracked by a KEP - -The definition of what constitutes an "enhancement" is a foundational concern -for the Kubernetes project. Roughly any Kubernetes user or operator facing -enhancement should follow the KEP process: if an enhancement would be described -in either written or verbal communication to anyone besides the KEP author or -developer then consider creating a KEP. One concrete example is an enhancement -which should be communicated to SIG Release or SIG PM. - -Similarly, any technical effort (refactoring, major architectural change) that -will impact a large section of the development community should also be -communicated widely. The KEP process is suited for this even if it will have -zero impact on the typical user or operator. - -As the local bodies of governance, SIGs should have broad latitude in describing -what constitutes an enhancement which should be tracked through the KEP process. -SIGs may find that helpful to enumerate what _does not_ require a KEP rather -than what does. SIGs also have the freedom to customize the KEP template -according to their SIG specific concerns. For example the KEP template used to -track API changes will likely have different subsections than the template for -proposing governance changes. However, as changes start impacting other SIGs or -the larger developer community outside of a SIG, the KEP process should be used -to coordinate and communicate. - -### KEP Template - -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 - conflicts. 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 artifacts. - * 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 `superseded-by`. - * In the form `KEP-123` -* **superseded-by** - * A list of KEPs that supersede 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 - working group -- **accepted**: the motivation has been accepted by the SIG or working group as in - road map -- **scoped**: the design has been approved by the SIG or working group -- **started**: the implementation of the KEP has begun -- **implemented**: the implementation of the KEP is complete -- **deferred**: the KEP has been postponed by the SIG or working group despite - agreement on the motivation -- **superseded**: the KEP has been superseded by another KEP -- **retired**: the implementation of the KEP has been removed -- **rejected**: the KEP has been rejected by the SIG or working group -- **orphaned**: the author or developer of the KEP is no longer willing or able - to complete implementation - -with possible paths through the state space - -- opened -> deferred (a) -- opened -> rejected (b) -- opened -> orphaned (c) -- opened -> accepted -> orphaned (d) -- opened -> accepted -> scoped -> superseded (e) -- opened -> accepted -> scoped -> orphaned (f) -- opened -> accepted -> scoped -> started -> retired (g) -- opened -> accepted -> scoped -> started -> orphaned (h) -- opened -> accepted -> scoped -> started -> superseded (i) -- opened -> accepted -> scoped -> started -> implemented (j) -- opened -> accepted -> scoped -> started -> implemented -> retired (k) - -the happy path is denoted by (j) where an KEP is opened; accepted by a SIG as in -their roadmap; fleshed out with a design; started; and finally implemented. As -Kubernetes continues to mature, hopefully metrics on the utilization of features -will drive decisions on what features to maintain and which to deprecate and so -it is possible that a KEP would be retired if its functionality no longer provides -sufficient value to the community. - -### Git and GitHub Implementation - -Practically an KEP would be implemented as a pull request to a central repository -with the following example structure - -``` -├── 0000-kep-template.md -├── CODEOWNERS -├── index.md -├── sig-architecture -│ ├── deferred -│ ├── orphaned -│ └── retired -├── sig-network -│ ├── deferred -│ ├── kube-dns -│ ├── orphaned -│ └── retired -├── sig-node -│ ├── deferred -│ ├── kubelet -│ ├── orphaned -│ └── retired -├── sig-release -│ ├── deferred -│ ├── orphaned -│ └── retired -├── sig-storage -│ ├── deferred -│ ├── orphaned -│ └── retired -├── unsorted-to-be-used-by-newcomers-only -└── wg-resource-management - ├── deferred - ├── orphaned - └── retired -``` - -where each SIG or working group is given a top level directory with subprojects -maintained by the SIG listed in sub directories. For newcomers to the community -an `unsorted-to-be-used-by-newcomers-only` directory may be used before an KEP -can be properly routed to a SIG although hopefully if discussion for a potential -KEP begins on the mailing lists proper routing information will be provided to -the KEP author. Additionally a top level index of KEPs may be helpful for people -looking for a complete list of KEPs. There should be basic CI to ensure that an -`index.md` remains up to date. - -Ideally no work would begin within the repositories of the Kubernetes organization -before a KEP has been approved by the responsible SIG or working group. While the -details of how SIGs organize their work is beyond the scope of this proposal one -possibility would be for each charter SIG to create a top level repository within -the Kubernetes org where implementation issues managed by that SIG would be filed. - -### KEP Editor Role - -Taking a cue from the [Python PEP process][], I believe that a group of KEP editors -will be required to make this process successful; the job of an KEP editor is -likely very similar to the [PEP editor responsibilities][] and will hopefully -provide another opportunity for people who do not write code daily to contribute -to Kubernetes. - -In keeping with the PEP editors which - -> Read the PEP to check if it is ready: sound and complete. The ideas must make -> technical sense, even if they don't seem likely to be accepted. -> The title should accurately describe the content. -> Edit the PEP for language (spelling, grammar, sentence structure, etc.), markup -> (for reST PEPs), code style (examples should match PEP 8 & 7). - -KEP editors should generally not pass judgement on a KEP beyond editorial -corrections. - -[Python PEP process]: https://www.python.org/dev/peps/pep-0001/ -[PEP editor responsibilities]: https://www.python.org/dev/peps/pep-0001/#pep-editor-responsibilities-workflow - -### Important Metrics - -It is proposed that the primary metrics which would signal the success or -failure of the KEP process are - -- how many "features" are tracked with a KEP -- distribution of time a KEP spends in each state -- KEP rejection rate -- PRs referencing a KEP merged per week -- number of issued open which reference a KEP -- number of contributors who authored a KEP -- number of contributors who authored a KEP for the first time -- number of orphaned KEPs -- number of retired KEPs -- number of superseded KEPs - -### Prior Art - -The KEP process as proposed was essentially stolen from the [Rust RFC process] which -itself seems to be very similar to the [Python PEP process][] - -[Rust RFC process]: https://github.com/rust-lang/rfcs - -## Graduation Criteria - -should hit at least the following milestones - -- a release note draft can be generated by referring primarily to KEP content -- a yearly road map is expressed as a KEP - -## Drawbacks - -Any additional process has the potential to engender resentment within the -community. There is also a risk that the KEP process as designed will not -sufficiently address the scaling challenges we face today. PR review bandwidth is -already at a premium and we may find that the KEP process introduces an unreasonable -bottleneck on our development velocity. - -It certainly can be argued that the lack of a dedicated issue/defect tracker -beyond GitHub issues contributes to our challenges in managing a project as large -as Kubernetes, however, given that other large organizations, including GitHub -itself, make effective use of GitHub issues perhaps the argument is overblown. - -The centrality of Git and GitHub within the KEP process also may place too high -a barrier to potential contributors, however, given that both Git and GitHub are -required to contribute code changes to Kubernetes today perhaps it would be reasonable -to invest in providing support to those unfamiliar with this tooling. - -Expanding the proposal template beyond the single sentence description currently -required in the [features issue template][] may be a heavy burden for non native -English speakers and here the role of the KEP editor combined with kindness and -empathy will be crucial to making the process successful. - -[features issue template]: https://github.com/kubernetes/features/blob/master/ISSUE_TEMPLATE.md - -## Alternatives - -This KEP process is related to -- the generation of a [architectural roadmap][] -- the fact that the [what constitutes a feature][] is still undefined -- [issue management][] -- the difference between an [accepted design and a proposal][] -- [the organization of design proposals][] - -this proposal attempts to place these concerns within a general framework. - -[architectural roadmap]: https://github.com/kubernetes/community/issues/952 -[what constitutes a feature]: https://github.com/kubernetes/community/issues/531 -[issue management]: https://github.com/kubernetes/community/issues/580 -[accepted design and a proposal]: https://github.com/kubernetes/community/issues/914 -[the organization of design proposals]: https://github.com/kubernetes/community/issues/918 - -### Github issues vs. KEPs - -The use of GitHub issues when proposing changes does not provide SIGs good -facilities for signaling approval or rejection of a proposed change to Kubernetes -since anyone can open a GitHub issue at any time. Additionally managing a proposed -change across multiple releases is somewhat cumbersome as labels and milestones -need to be updated for every release that a change spans. These long lived GitHub -issues lead to an ever increasing number of issues open against -`kubernetes/features` which itself has become a management problem. - -In addition to the challenge of managing issues over time, searching for text -within an issue can be challenging. The flat hierarchy of issues can also make -navigation and categorization tricky. While not all community members might -not be comfortable using Git directly, it is imperative that as a community we -work to educate people on a standard set of tools so they can take their -experience to other projects they may decide to work on in the future. While -git is a fantastic version control system (VCS), it is not a project management -tool nor a cogent way of managing an architectural catalog or backlog; this -proposal is limited to motivating the creation of a standardized definition of -work in order to facilitate project management. This primitive for describing -a unit of work may also allow contributors to create their own personalized -view of the state of the project while relying on Git and GitHub for consistency -and durable storage. - -## Unresolved Questions - -- How reviewers and approvers are assigned to a KEP -- Approval decision process for a KEP -- Example schedule, deadline, and time frame for each stage of a KEP -- Communication/notification mechanisms -- Review meetings and escalation procedure -- Decision on where development should occur - -## Mentors - -- caleb miles - - github: [calebamiles](https://github.com/calebamiles/) - - slack: [calebamiles](https://coreos.slack.com/team/caleb.miles) - - email: [caleb.miles@coreos.com](mailto:caleb.miles@coreos.com) - - pronoun: "he" diff --git a/contributors/design-proposals/architecture/OWNERS b/contributors/design-proposals/architecture/OWNERS index 2df39a59..87364abb 100644 --- a/contributors/design-proposals/architecture/OWNERS +++ b/contributors/design-proposals/architecture/OWNERS @@ -1,6 +1,8 @@ reviewers: - sig-architecture-leads + - jbeda approvers: - sig-architecture-leads + - jbeda labels: - sig/architecture |
