Revise KEP template

[justaugustus]

Brings @pwittrock's updates in #690 over...

Update KEP template

• Add release checklist
• Expand upon graduation criteria
• Add test plan section
• Add upgrade / downgrade section
• Add version skew section

Additionally:

• Clarify some requirements in Release Team checklist
• Do away with KEP number in template

Phil and I discussed earlier in the week that I'd pick this up, so he doesn't have to be responsible for iterating on any changes suggested.

/assign @calebamiles @spiffxp @pwittrock @bgrant0607
/sig pm architecture
/hold

Fixes: kubernetes/community#2245

[justaugustus]

/milestone v1.14

[justaugustus]

/remove-milestone v1.14
/milestone keps-beta

[justaugustus]

Blockade for NEXT_KEP_NUMBER added in kubernetes/test-infra#10856.

[ixdy]

Lines 35-38 still reference "KEP number", as does the YAML template.

[spiffxp]

Aside from @ixdy 's nit this LGTM

[spiffxp]

/unassign @derekwaynecarr
/cc @derekwaynecarr
FYI @timothysc this is how we suggest requesting review, it shows up on https://gubernator.k8s.io/pr just as much as /assign does

[spiffxp]

/cc @lavalamp @michmike
per #703 (comment)

[spiffxp]

(also, meta point, this is way too many people to constructively drive forward in a small incremental step, this turned into a way way bigger PR than I had hoped we would start with)

[jbeda]

Biggest comment is that this is no longer really a template but rather instructions. Perhaps break out into a new doc and/or update https://github.com/kubernetes/enhancements/blob/master/keps/0001-kubernetes-enhancement-proposal-process.md?

Or merge this into the first kep?

But don't synchronize on me though!

[jbeda]

May not make sense to put that in this section fo the template/instructions but we can put it someplace.

[lavalamp]

I still don't really understand why the "approvers" and "reviewers" section of KEPs exist.

If it's about people who are supposed to approve/review the KEP itself, don't we have owners files for that? KEPs are in separate directories now.

If it's about people who are going to help approve and/or review the code changes (e.g., demonstrating that you've lined up sufficient bandwidth in the schedules of busy folks to actually get the changes made), it's probably named wrong.

Actually IMO it's totally ambiguous right now and that section of the KEP could either be renamed or have a comment to make it clear what it means.

[justaugustus]

Part of the goal is disambiguate the KEP itself from the place it lives / things that operate over it.
If someone, for whatever crazy reason, printed out a KEP, would they, at a glance, be able to understand who authored, edited, reviewed, and approved it?

OWNERS leads me to looking up the OWNERS_ALIASES, neither or which are guaranteed to stay the same over time. If I needed to reach out to someone to discuss the KEP, I would need more context.

We can do better on making that more clear in the documentation. I've added an AI in #822.

[bgrant0607]

My intent was that the leads of the area (e.g., SIG TLs, subproject owners) would assign specific reviewers and approvers for each KEP, so that there are specific people that can review/approve, shepherd, serve as points of contact, etc. Always assigning SIG TLs to these roles is unrealistic due to time constraints, and if it's just everyone in a SIG, then it's easy to fall through the cracks or to get conflicting guidance. Unclear OARP is one of our biggest problems.

[lavalamp]

Honestly from the perspective of people wanting to file KEPs this seems like obscure busywork. Why don't we make a bot to file these issues?

[justaugustus]

I think that's something we can start to look at, once we've stabilized more of the process.
We'd need to clean the metadata for all KEPs and scrub the existing Enhancement Issues beforehand. I've added an AI in #822.

[lavalamp]

Are KEPs design docs or requirements docs?

People have said "both" but I'm not convinced that's a good answer. There is no reason to suppose that the set of people who know what good goals are has a lot of overlap with the set of people who will be good at charting a path to achieving the goals.

I personally feel that it's reasonable to hold a vote on goals (i.e. requirements), as long as they're appropriately phrased (e.g., "is problem X an important problem for the project to solve" NOT "is changing the frobber API to interoperate with the thingy a good idea"). It is not a good idea to vote on solutions (designs), that should be handled by the right technical folks. (I think any formal specification of this distinction can be gamed, unfortunately.)

[justaugustus]

I don't have a great answer for this at the moment. I think that "both" is the right answer currently, simply because all SIGs have slightly different operating mechanisms, each KEP isn't strictly technical content (it may be process-related, like this one), etc.

Authors and editors have the obvious roles.
I see reviewers as those who can help tighten the scope of a KEP and better define if it's something that needs heavy technical insight. Depending on the scope, those reviewers could very well be technical reviewers.

Approvers then act as the rubber stamp to signal SIG acceptance.

I've added an AI in #822 to firm up docs on this.

[bgrant0607]

Requirements vs design: They must cover both. Whether requirements should be agreed upon before discussing the design is more of a process question, but it also depends on the complexity of the change. Simple changes could address both simultaneously.

[lavalamp]

Is there a way to have comments in markdown? Perhaps leave these as suggestions inside a comment; outside of the comment I'd say something like "TBD after beta" with the hint that people will update the KEP once they are in beta and know what they'll do?

[justaugustus]

This section is only meant as examples, so authors should feel free to remove.

[justaugustus]

@jbeda -- agreed that this has more instructions that the initial intent. I've taken an AI to pull those out and move them more top-level after this merges.

--

Given the spirit of merge early, iterate often (as @spiffxp was alluding to) do we think this is in a decent place to merge and iterate?
It's significantly better than the previous one, thanks to all of the reviews here.

I've captured the review comments that need to addressed in #822, and I can start knocking them out once this lands.

WDYT?

[jbeda]

@justaugustus SGTM! Ship it!

[justaugustus]

Alrighty, releasing the hold.
/hold cancel

The next /lgtm will ship it!

[idvoretskyi]

/lgtm

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: idvoretskyi, justaugustus

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

• keps/OWNERS [idvoretskyi,justaugustus]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[idvoretskyi]

@justaugustus you got it!

[spiffxp]

thanks for moving forward on this

[bgrant0607]

This applies to nodes generally, so kube-proxy and any other node agents as well as kubelet.