KEP-1a: Meta KEP Implementation #2655
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,217 @@ | ||
| --- | ||
| kep-number: 1a | ||
| title: Meta KEP Implementation | ||
| authors: | ||
| - "@justaugustus" | ||
| - "@calebamiles" | ||
| - "@jdumars" | ||
| owning-sig: sig-pm | ||
| participating-sigs: | ||
| - sig-architecture | ||
| reviewers: | ||
| - "@idvoretskyi" | ||
| - "@timothysc" | ||
| approvers: | ||
| - "@bgrant0607" | ||
| - "@jbeda" | ||
| editor: | ||
| creation-date: 2018-09-08 | ||
| last-updated: 2018-09-19 | ||
| status: provisional | ||
| see-also: | ||
| - KEP-1 | ||
| replaces: | ||
| superseded-by: | ||
| --- | ||
|
|
||
| # Meta KEP Implementation | ||
|
|
||
| ## Table of Contents | ||
|
|
||
| - [Table of Contents](#table-of-contents) | ||
| - [Summary](#summary) | ||
| - [Motivation](#motivation) | ||
| - [Why another KEP?](#why-another-kep) | ||
| - [Non-Goals](#non-goals) | ||
| - [Proposal](#proposal) | ||
| - [Implementation Details / Notes / Constraints](#implementation-details--notes--constraints) | ||
| - [Define](#define) | ||
| - [Organize](#organize) | ||
| - [Visibility and Automation](#visibility-and-automation) | ||
| - [Constraints](#constraints) | ||
| - [Graduation Criteria](#graduation-criteria) | ||
| - [Implementation History](#implementation-history) | ||
|
|
||
| ## Summary | ||
|
|
||
| Drive KEP adoption through improved process, documentation, visibility, and automation. | ||
|
|
||
| ## Motivation | ||
|
|
||
| The KEP process is the standardized structure for proposing changes to the Kubernetes project. | ||
|
|
||
| In order to graduate KEPs to GA, we must iterate over the implementation details. | ||
|
|
||
| This KEP seeks to define actionable / delegable items to move the process forward. | ||
|
|
||
| Finally, by submitting a KEP, we gain an opportunity to dogfood the process and further identify areas for improvement. | ||
|
|
||
| ### Why another KEP? | ||
|
|
||
| As [KEP-1] is currently de facto for the project, we must be careful to make changes to it in an iterative and atomic fashion. | ||
|
|
||
| When proposing a KEP, we action over some unit of work, usually some area of code. | ||
|
|
||
| In this instance, we treat [KEP-1] as the unit of work. That said, this would be considered a meta-KEP of the meta-KEP. | ||
|
|
||
| ### Non-Goals | ||
|
|
||
| - API Review process | ||
| - Feature request triage | ||
| - Developer guide | ||
|
|
||
| ## Proposal | ||
|
|
||
| ### Implementation Details / Notes / Constraints | ||
|
|
||
| #### Define | ||
|
|
||
| - Refine existing KEP documentation | ||
| - Define KEP [DACI] | ||
| - Glossary of terms (enhancement, KEP, feature, etc.) | ||
| - KEP Workflow | ||
| - KEP states | ||
| - Entry / exit criteria | ||
|
|
||
| #### Organize | ||
|
|
||
| - Move KEPs from flat-files to a directory structure: | ||
| ``` | ||
| ├── keps # top-level directory | ||
| │ ├── sig-beard # SIG directory | ||
| | | ├── 9000-beard-implementation-api # KEP directory | ||
| | | | ├── kep.md (required) # KEP (multi-release work) | ||
| | | | ├── experience_reports (required) # user feedback | ||
| | | | │ ├── alpha-feedback.md | ||
| | | | │ └── beta-feedback.md | ||
| | | | ├── features # units of work that span approximately one release cycle | ||
| | | | │ ├── feature-01.md | ||
| | | | │ ├── ... | ||
| | | | │ └── feature-n.md | ||
| | | | ├── guides | ||
| | | | | ├── guide-for-developers.md (required) | ||
|
There was a problem hiding this comment. Guides seem like something that goes on the Docs site. There was a problem hiding this comment. This is about creating a place to store the "vomit draft" quality documentation (Andrew's term). Rust has a similar setup for their process which I like. I have schemes to one day generate more of the documentation from content stored in the KEP (to reinforce the idea that they're living documents) but again table stakes There was a problem hiding this comment. I do like the idea of having a directory for keps. There are then options to make it bigger and evolve it over time. I would look to minimize the amount of required stuff here and not be too prescriptive of the breakdown. We already have a problem where there are a lot of rules and it is hard to get people to understand the purpose of them. |
||
| | | | | ├── guide-for-teachers.md (required) | ||
| | | | | ├── guide-for-operators.md (required) | ||
| | | | | └── guide-for-project-maintainers.md | ||
| | | | ├── index.json (required) # used for site generation e.g., Hugo | ||
| | | | ├── metadata.yaml (required) # used for automation / project tracking | ||
| | | └── └── OWNERS | ||
| │ ├── sig-foo | ||
| | ├── ... | ||
| | └── sig-n | ||
| ``` | ||
|
|
||
| metadata.yaml would contain information that was previously in a KEP's YAML front-matter: | ||
|
|
||
| ``` | ||
| --- | ||
|
There was a problem hiding this comment. This strikes me as a lot of metadata required to write a KEP. There was a problem hiding this comment. should be generated by automation in the general case There was a problem hiding this comment. +1 to automation managing the metadata as much as possible. |
||
| authors: # required | ||
| - "calebamiles" # just a GitHub handle for now | ||
| - "jbeda" | ||
| title: "Kubernetes Enhancement Proposal process" | ||
| number: 42 # required | ||
| owning-sig: "sig-pm" # required | ||
| participating-sigs: | ||
| - "sig-architecture" | ||
| - "sig-contributor-experience" | ||
| approvers: # required | ||
| - "bgrant0607" # just a GitHub handle for now | ||
| reviewers: | ||
| - "justaugustus" # just a GitHub handle for now | ||
| - "jdumars" | ||
| editors: | ||
| - null # generally omit empty/null fields | ||
| status: "active" # required | ||
| github: | ||
| issues: | ||
| - null # GitHub url | ||
| pull_requests: | ||
| - null # GitHub url | ||
| projects: | ||
| - project_id: null | ||
| card_id: null | ||
| releases: # required | ||
| - k8s_version: v1.9 | ||
| kep_status: "active" | ||
| k8s_status: "alpha" # one of alpha|beta|GA | ||
| - k8s_version: v1.10 | ||
| kep_status: "active" | ||
| k8s_status: "alpha" | ||
| replaces: | ||
| - kep_location: null | ||
| superseded-by: | ||
| - kep_location: null | ||
| created: 2018-01-22 # in YYYY-MM-DD | ||
| updated: 2018-09-04 | ||
| ``` | ||
|
|
||
| - Move existing KEPs into [k/features] | ||
| - Create a `kind/kep` label for [k/community] and [k/features] | ||
| - For `k/community`: | ||
| - Label incoming KEPs as `kind/kep` | ||
| - Enable searches of `org:kubernetes label:kind/kep`, so we can identify active PRs to `k/community` and reroute the PR authors to `k/enhancements` (depending on the state) | ||
| - For `k/enhancements` (fka `k/features`): | ||
| - Label incoming KEPs as `kind/kep` | ||
| - Classify KEP submissions / tracking issues as `kind/kep`, differentiating them from `kind/feature` | ||
| - Move existing design proposals into [k/features] | ||
| - Move existing architectural documents into [k/features] (process TBD) | ||
| - Deprecate design proposals | ||
| - Rename [k/features] to [k/enhancements] | ||
| - Create tombstones / redirects to [k/enhancements] | ||
| - Prevent new KEPs and design proposals from landing in [k/community] | ||
| - Remove `kind/kep` from [k/community] once KEP migration is complete | ||
| - Correlate existing Feature tracking issues with links to KEPs | ||
| - Fix [KEP numbering races] by using the GitHub issue number of the KEP tracking issue | ||
|
There was a problem hiding this comment. I'm not a huge fan of this but I guess it is ok. We'll have sparse numbering as there will be other PRs. One thing that I want to do regardless is encourage people to check in early. If the latency between PR for new kep and commit is small these races will be minimal. We can and should build some presubmit to prevent races too. In any case, if we use the PR number as the KEP number there will still have to be a dance where people will create a change, submit a PR, update their files and submit/push another change to that PR. That dance isn't obvious and will make this a bit harder. |
||
| - Coordination of existing KEPs to use new directory structure (with SIG PM guidance per SIG) | ||
|
|
||
| #### Visibility and Automation | ||
|
|
||
| - Create tooling to: | ||
| - Generate KEP directories and associated metadata | ||
| - Present KEPs, through some easy to use mechanism e.g., https://enhancements.k8s.io. This would be a redesigned version of https://contributor.kubernetes.io/keps/. We envision this site / repo having at least three directories: | ||
|
There was a problem hiding this comment. We are already building out contributors.k8s.io and we should put the keps there. That was one of the main reasons for that site. /cc @castrojo There was a problem hiding this comment. We can totally do this, we just need the repo URL when it's created and we can implement it. Doing it with three sections wouldn't be a problem. Hugo can be sensitive to the metadata though, it'd be great if the tooling could lint it before hugo consumes it. |
||
| - `keps/` (KEPs) | ||
| - `design-proposals/` (historical design proposals from https://git.k8s.io/community/contributors/design-proposals) | ||
| - `arch[itecture]|design/` (design principles of Kubernetes, derived from reorganizing https://git.k8s.io/community/contributors/devel, mentioned [here](https://github.com/kubernetes/community/issues/2565#issuecomment-419185591)) | ||
| - Enable project tracking across SIGs | ||
|
|
||
| #### Constraints | ||
|
|
||
| - Preserve git history | ||
| - Preserve issues | ||
| - Preserve PRs | ||
|
|
||
| ## Graduation Criteria | ||
|
|
||
| Throughout implementation, we will be reaching out across the project to SIG leadership, approvers, and reviewers to capture feedback. | ||
|
|
||
| While graduation criteria has not strictly been defined at this stage, we will define it in future updates to this KEP. | ||
|
|
||
| ## Implementation History | ||
|
|
||
| - 2018-08-20: (@timothysc) Issue filed about repo separation: https://github.com/kubernetes/community/issues/2565 | ||
| - 2018-08-30: SIG Architecture meeting mentioning the need for a clearer KEP process - https://youtu.be/MMJ-zAR_GbI | ||
| - 2018-09-06: SIG Architecture meeting agreeing to move forward with a KEP process improvement effort to be co-led with SIG PM (@justaugustus / @jdumars) - https://youtu.be/fmlXkN4DJy0 | ||
| - 2018-09-10: KEP-1a submitted for review | ||
| - YYYY-MM-DD: the `Summary` and `Motivation` sections being merged signaling SIG acceptance | ||
| - YYYY-MM-DD: the `Proposal` section being merged signaling agreement on a proposed design | ||
| - YYYY-MM-DD: the date implementation started | ||
| - YYYY-MM-DD: the first Kubernetes release where an initial version of the KEP was available | ||
| - YYYY-MM-DD: the version of Kubernetes where the KEP graduated to general availability | ||
|
|
||
|
|
||
| [DACI]: https://www.atlassian.com/team-playbook/plays/daci | ||
| [KEP-1]: 0001-kubernetes-enhancement-proposal-process.md | ||
| [KEP numbering races]: https://github.com/kubernetes/community/issues/2245 | ||
| [k/community]: http://git.k8s.io/community | ||
| [k/enhancements]: http://git.k8s.io/enhancements | ||
| [k/features]: http://git.k8s.io/features | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Why are KEPs by SIG? This means people have to look in multiple places to find stuff. Compare to python PEP-0 where you only have to look at one page to find all the KEPs.
Or the index of all the RFCs from IETF:
https://tools.ietf.org/rfc/index
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
KEPs are by SIG in order to reuse the
OWNERSmechanism for effective delegation. It follows the reorg ofdesign-proposals/. Now that we have subprojects I can imagine yet another layer of organization but I agree that we'll need to think about how to build a holistic view of all the content; I admit that I haven't given this question enough thought but I'd like to get some table stakes out of the way first. I do like that for [smaller] projects like Rust you can see all the content in one place although even for a smallish surface area like Rust there are some other RFCs floating around in repos for specific subteams. We did see immediately that we were having problems with the flat structure in terms of review bandwidth and I was becoming a blocker which is no bueno.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I feel like repository layout and visual presentation shouldn't be conflated. The job of a KEP is to convey an intent, as well as track how the work to satisfy the intent evolves over time. With that lens, the layout is best oriented to serve the highest stakeholders which are subproject participants first and foremost, SIGs second, consumers like the release team third, and causal observers dead last. Focusing on the current visualization as a starting point feels like a red herring since the KEP process itself, state transition definitions, cli tooling, etc. is not formalized or implemented. Reuse of the OWNERS construct at the subproject level makes a ton of sense.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm stuck on repo layout and such because ever since KEPs were first suggested we've been using the "automation will make this more digestible" line, yet the automation hasn't arrived. Until it does, this is the experience we're left with. Imposing even more friction up front doesn't fill me with confidence that automation will come any sooner.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The original thinking here is that there would broadly be two types of keps -- those that are "local" to a SIG whereby the SIG is reusing the KEP process for their own internal decision making process. This might leak out where it is mostly in one SIG with a few other SIGs weighing in.
Contrast this to KEPs that are wide reaching and impact most of the project. These should get wider review and have a wider set of approvers. I can see situations where something might start out "SIG local" but become "k8s wide" as the implications are realized.
I don't think we did a good job of making this clear.
I think we should either make it clear that there are two types of KEPs and perhaps have another top level directory for sig-local keps (
sig-keps?) or we should just say that every kep is top level and collapse the hierarchy.That being said -- I'd suggest that we move forward in some concrete ways that will improve things. We can always change this again in the future if we need to.