From cb33c4ed26b19169befa11fe2b5026f0abc01b2c Mon Sep 17 00:00:00 2001 From: Manuel Alejandro de Brito Fontes Date: Thu, 18 Jul 2019 18:14:12 -0400 Subject: [PATCH] Start using KEPs for new features or breaking changes --- docs/enhancements/README.md | 28 ++++ docs/enhancements/YYYYMMDD-kep-template.md | 182 +++++++++++++++++++++ hack/tools.go | 1 + hack/update-toc.sh | 34 ++++ 4 files changed, 245 insertions(+) create mode 100644 docs/enhancements/README.md create mode 100644 docs/enhancements/YYYYMMDD-kep-template.md create mode 100755 hack/update-toc.sh diff --git a/docs/enhancements/README.md b/docs/enhancements/README.md new file mode 100644 index 000000000..0c891adad --- /dev/null +++ b/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. diff --git a/docs/enhancements/YYYYMMDD-kep-template.md b/docs/enhancements/YYYYMMDD-kep-template.md new file mode 100644 index 000000000..60bf44207 --- /dev/null +++ b/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 <!-- toc --&rt;<!-- /toc --&rt; tags, and then generate with `hack/update-toc.sh`. + + +- [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) + + +## 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. diff --git a/hack/tools.go b/hack/tools.go index ed3216805..f2d455a94 100644 --- a/hack/tools.go +++ b/hack/tools.go @@ -21,5 +21,6 @@ limitations under the License. package tools import ( + _ "github.com/tallclair/mdtoc" _ "k8s.io/code-generator" ) diff --git a/hack/update-toc.sh b/hack/update-toc.sh new file mode 100755 index 000000000..5ce87b4b9 --- /dev/null +++ b/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 '' | xargs mdtoc --inplace