KEP numbering is broken

[tallclair]

Here are the current keps, sorted by filename number and displayed alongside the metadata number:

0000:
  ./0000-kep-template.md  -  0

0001:
  ./0001-kubernetes-enhancement-proposal-process.md  -  1

0002:
  ./sig-cloud-provider/0002-cloud-controller-manager.md  -  2

0003:
  ./sig-cluster-lifecycle/0003-cluster-api.md  -  3

0004:
  ./sig-cluster-lifecycle/0004-bootstrap-checkpointing.md  -  4

0005:
  ./sig-contributor-experience/0005-contributor-site.md  -  5

0006:
  ./0006-apply.md  -  6

0007:
  ./sig-contributor-experience/0007-20180403-community-forum.md  -  0007
  ./sig-network/0007-pod-ready++.md  -  1

0008:
  ./sig-cluster-lifecycle/0008-20180504-kubeadm-config-beta.md  -  draft-20180412
  ./0008-20180430-promote-sysctl-annotations-to-fields.md  -  8
  ./sig-cli/0008-kustomize.md  -  8

0009:
  ./0009-node-heartbeat.md  -  8

0010:
  ./sig-network/0010-20180314-coredns-GA-proposal.md  -  10

0011:
  ./sig-network/0011-ipvs-proxier.md  -  TBD

0012:
  ./sig-network/0012-20180518-coredns-default-proposal.md  -  11

The problems include number collisions & metadata / filename mismatch. Due to these problems, the current numbering only provides friction & confusion. I think the numbers either need to be abandoned, or automation needs to be added to ensure the correct numbering process is followed.

[tallclair]

/sig contributor-experience
/assign calebamiles

[k8s-ci-robot]

@tallclair: GitHub didn't allow me to assign the following users: calebmiles.

Note that only kubernetes members and repo collaborators can be assigned.

In response to this:

/sig contributor-experience
/assign calebmiles

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[tallclair]

/cc @kubernetes/sig-architecture-bugs

[justaugustus]

+1
Do we think it's enough to just have KEPs organized in folders by SIG and abandon the numbering scheme?

...or perhaps have the numbering be based on the date of the proposal e.g., sig-pm/180625-really-cool-kep.md?

[jdumars]

I'm putting this on the SIG-Architecture agenda for this week. Hopefully we'll get to it.

[bgrant0607]

This came up in the original KEP discussions. I think there was some assumption that an "editor" would assign numbers post-merge.

I am a fan of the date approach.

I think the intent of the numbering is, at a glance, to get some sense of which KEPs are more recent.

[tallclair]

Why not just use the initial PR number? If the goal is to increase number density, we could just have a dedicated repo for KEPs. I think the number was intended to be a UID, so that related KEPs could be referred to unambiguously.

[justaugustus]

Going to plug the date approach again, since it gives you an immediate idea of how recent the proposals are. Not sure that we need another repo to track these, if we can think of a reasonable structure, but just my $0.02.

[thockin]

I actually think a KEP repo makes sense. I'm trying to keep up on KEPs, but the volume of other community-repo stuff makes it very hard.

…

On Wed, Jun 27, 2018 at 10:52 AM Tim Allclair (St. Clair) < ***@***.***> wrote: Why not just use the initial PR number? If the goal is to increase number density, we could just have a dedicated repo for KEPs. I think the number was intended to be a UID, so that related KEPs could be referred to unambiguously. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#2245 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AFVgVE1T7Dw93_GvaY8Hup6C6wz3uHwmks5uA8ZygaJpZM4UjoC2> .

[bgrant0607]

Or a KEP repo just for the backlog?

That would be similar to what is proposed for the API review process:
https://docs.google.com/document/d/1OkSQngGem7xaENqaO8jzHLDSSIGh2obPUaJGAFDwTUE/edit#

We don't have a clean division between KEPs, design proposals, and development docs right now. I wouldn't want them to live in separate repos.

[jbeda]

Sorry for being late to the party here.

I like the date approach. The one downside to that it is that it is difficult to refer to a KEP easily. I was looking forward to being able to talk about KEP 123 and have everyone know what we were talking about. As we have overlapping KEPs that deprecate old KEPs, etc. it is nice to have a number. This works well for RFCs and PEPs.

I'm not a fan of using the PR number. This locks us to github in a way that isn't great. If we ever migrate someplace else that counter gets lost and may not translate.

I don't think it'd be that hard to have a presubmit hook for this that runs. Seems like a quick hack. (I'd volunteer but I've never done one before and I'm not sure what system to integrate with and where/how to test.)

One other point -- the goal of the KEP process was to check in early to avoid some of this. Ideally a new KEP proposal shouldn't sit more than a day or two. All real discussion and refinement would happen in follow on PRs. I'd love all of us to encourage people to check in early and often with KEPs.

[cblecker]

Another out in the world example of how this is handled:
In the IETF, draft documents are always just draft-name-00 with the 00 being incremented. When something is accepted for RFC publication, then it's assigned a number. So perhaps all initial drafts get merged as draft, but then once the status in the sig goes to ACCEPTED, then an incremental number is assigned?

[justaugustus]

Any updates on this?

[jdumars]

My recommendation is that we separate KEP implementation tracking from the technical aspects of the KEP itself. All KEPs are tracked by SIG architecture currently in https://github.com/kubernetes-sigs/architecture-tracking via https://github.com/kubernetes-sigs/architecture-tracking/projects/2 The KEP creator could create the tracking issue and use that number as the KEP number. You will note on that board the high number of duplicates. This will immediately fix the problem. If this works, I will update the KEP process documentation and communicate it to the greater community.

[jbeda]

Jaice -- do you think we need a tracking issue on the board? Not all KEPs will require SIG-architecture to be involved. What about KEPs that are local to a SIG?

[tallclair]

/assign @jdumars

[bgrant0607]

FWIW, I don't foresee people referring to KEPs by numbers. I don't know many others who regularly refer to issues and PRs by number. :-)

The number not being finalized while the KEP is actively being discussed also leads to just referring to the KEP by topic.

[justaugustus]

From @justinsb in #2834:

There are 2 KEP 30s:

https://github.com/kubernetes/community/blob/master/keps/sig-api-machinery/0030-storage-migration.md

https://github.com/kubernetes/community/blob/master/keps/sig-network/0030-nodelocal-dns-cache.md

I think there are also two KEP 28s, two KEP 18s, three KEP 15s.

I'm guessing that rebase-needed detection doesn't work the way we think it does...

[BenTheElder]

rebase needed basically asks github if the PR needs rebase IIRC, it does this on some pretty low polling interval (daily?) and otherwise might occasionally get an event from github sooner than that.

[BenTheElder]

it's definitely not something to rely on heavily, just a handy nudge when it works

[justaugustus]

Thanks for the context, Ben!

[justaugustus]

This will be removed in kubernetes/enhancements#703
I've commented on open KEP PRs to request that authors remove references to KEP numbers.

[justaugustus]

/milestone v1.14

[justaugustus]

/remove-sig pm
/sig architecture
/area enhancements