Start using KEPs for new features or breaking changes

docs/enhancements/README.md

@@ -0,0 +1,28 @@
+# Kubernetes Enhancement Proposals (KEPs)
+
+A Kubernetes Enhancement Proposal (KEP) is a way to propose, communicate and coordinate on new efforts for the Kubernetes project. For this reason, the `ingress-nginx` project is adopting it.
+
+## Quick start for the KEP process
+
+Follow the process outlined in the [KEP template](YYYYMMDD-kep-template.md)
+
+### Do I have to use the KEP process?
+
+No... but we hope that you will.
+Over time having a rich set of KEPs in one place will make it easier for people to track what is going on in the community and find a structured historic record.
+
+KEPs are only required when the changes are wide ranging and impact most of the project.
+
+### Why would I want to use the KEP process?
+
+Our aim with KEPs is to clearly communicate new efforts to the Kubernetes contributor community.
+As such, we want to build a well curated set of clear proposals in a common format with useful metadata.
+
+Benefits to KEP users (in the limit):
+
+* Exposure on a kubernetes blessed web site that is findable via web search engines.
+* Cross indexing of KEPs so that users can find connections and the current status of any KEP.
+* A clear process with approvers and reviewers for making decisions.
+  This will lead to more structured decisions that stick as there is a discoverable record around the decisions.
+
+We are inspired by IETF RFCs, Python PEPs, and Rust RFCs.

docs/enhancements/YYYYMMDD-kep-template.md

@@ -0,0 +1,182 @@
+---
+title: KEP Template
+authors:
+  - "@janedoe"
+reviewers:
+  - TBD
+  - "@alicedoe"
+approvers:
+  - TBD
+  - "@oscardoe"
+editor: TBD
+creation-date: yyyy-mm-dd
+last-updated: yyyy-mm-dd
+status: provisional|implementable|implemented|deferred|rejected|withdrawn|replaced
+see-also:
+  - "/docs/enhancements/20190101-we-heard-you-like-keps.md"
+  - "/docs/enhancements/20190102-everyone-gets-a-kep.md"
+replaces:
+  - "/docs/enhancements/20181231-replaced-kep.md"
+superseded-by:
+  - "/docs/enhancements/20190104-superceding-kep.md"
+---
+
+# 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 title should be lowercased and spaces/punctuation should be replaced with `-`.
+
+To get started with this template:
+
+1. **Make a copy of this template.**
+  Create a copy of this template and name it `YYYYMMDD-my-title.md`, where `YYYYMMDD` is the date the KEP was first drafted.
+1. **Fill out the "overview" sections.**
+  This includes the Summary and Motivation sections.
+  These should be easy if you've preflighted the idea of the KEP in an issue.
+1. **Create a PR.**
+  Assign it to folks that are sponsoring this process.
+1. **Create an issue**
+  When filing an enhancement tracking issue, please ensure to complete all fields in the template.
+1. **Merge early.**
+  Avoid getting hung up on specific details and instead aim to get the goal of the KEP merged quickly.
+  The best way to do this is to just start with the "Overview" sections and fill out details incrementally in follow on PRs.
+  View anything marked as a `provisional` as a working document and subject to change.
+  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.
+
+The canonical place for the latest set of instructions (and the likely source of this file) is [here](/keps/YYYYMMDD-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.
+
+Ensure the TOC is wrapped with <code>&lt;!-- toc --&rt;&lt;!-- /toc --&rt;</code> tags, and then generate with `hack/update-toc.sh`.
+
+<!-- toc -->
+- [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)
+  - [Risks and Mitigations](#risks-and-mitigations)
+- [Design Details](#design-details)
+  - [Test Plan](#test-plan)
+    - [Removing a deprecated flag](#removing-a-deprecated-flag)
+- [Implementation History](#implementation-history)
+- [Drawbacks [optional]](#drawbacks-optional)
+- [Alternatives [optional]](#alternatives-optional)
+<!-- /toc -->
+
+## Summary
+
+The `Summary` section is incredibly important for producing high quality user-focused documentation such as release notes or a development roadmap.
+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.
+
+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 this 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.
+
+### Risks and Mitigations
+
+What are the risks of this proposal and how do we mitigate.
+Think broadly.
+For example, consider both security and how this will impact the larger kubernetes ecosystem.
+
+How will security be reviewed and by whom?
+How will UX be reviewed and by whom?
+
+Consider including folks that also work outside project.
+
+## Design Details
+
+### Test Plan
+
+**Note:** *Section not required until targeted at a release.*
+
+Consider the following in developing a test plan for this enhancement:
+
+- Will there be e2e and integration tests, in addition to unit tests?
+- How will it be tested in isolation vs with other components?
+
+No need to outline all of the test cases, just the general strategy.
+Anything that would count as tricky in the implementation and anything particularly challenging to test should be called out.
+
+All code is expected to have adequate tests (eventually with coverage expectations).
+Please adhere to the [Kubernetes testing guidelines][testing-guidelines] when drafting this test plan.
+
+[testing-guidelines]: https://git.k8s.io/community/contributors/devel/sig-testing/testing.md
+
+#### Removing a deprecated flag
+
+- Announce deprecation and support policy of the existing flag
+- Two versions passed since introducing the functionality which deprecates the flag (to address version skew)
+- Address feedback on usage/changed behavior, provided on GitHub issues
+- Deprecate the flag
+
+## 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 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.

hack/tools.go

@@ -21,5 +21,6 @@ limitations under the License.
 package tools
 
 import (
+	_ "github.com/tallclair/mdtoc"
 	_ "k8s.io/code-generator"
 )

hack/update-toc.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+
+# Copyright 2019 The Kubernetes Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+set -o errexit
+set -o nounset
+set -o pipefail
+
+export KUBE_ROOT=$(dirname "${BASH_SOURCE}")/..
+
+# Install tools we need, but only from vendor/...
+cd ${KUBE_ROOT}
+go install ./vendor/github.com/tallclair/mdtoc
+if ! which mdtoc >/dev/null 2>&1; then
+    echo "Can't find mdtoc - is your GOPATH 'bin' in your PATH?" >&2
+    echo "  GOPATH: ${GOPATH}" >&2
+    echo "  PATH:   ${PATH}" >&2
+    exit 1
+fi
+
+# Update tables of contents if necessary.
+grep --include='*.md' -rl docs/enhancements/* -e '<!-- toc -->' | xargs mdtoc --inplace