diff --git a/Makefile b/Makefile index cabbfe8b4d51..82e62f30592e 100644 --- a/Makefile +++ b/Makefile @@ -113,6 +113,14 @@ gomod-verify: $(GO_CMD) mod tidy git --no-pager diff --exit-code go.mod go.sum +.PHONY: toc-update +toc-update: + ./hack/update-toc.sh + +.PHONY: toc-verify +toc-verify: + ./hack/verify-toc.sh + .PHONY: vet vet: ## Run go vet against code. $(GO_CMD) vet ./... @@ -131,7 +139,7 @@ ci-lint: golangci-lint $(GOLANGCI_LINT) run --timeout 7m0s .PHONY: verify -verify: gomod-verify vet ci-lint fmt-verify manifests generate +verify: gomod-verify vet ci-lint fmt-verify toc-verify manifests generate git --no-pager diff --exit-code config/components apis ##@ Build diff --git a/hack/.notableofcontents b/hack/.notableofcontents new file mode 100644 index 000000000000..e69de29bb2d1 diff --git a/hack/update-toc.sh b/hack/update-toc.sh new file mode 100755 index 000000000000..366354b8bf9c --- /dev/null +++ b/hack/update-toc.sh @@ -0,0 +1,52 @@ +#!/usr/bin/env bash + +# Copyright 2022 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 + +# keep in sync with hack/verify-toc.sh +TOOL_VERSION=b8c54a57d69f29386d055584e595f38d65ce2a1f + +# cd to the root path +ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd -P)" +cd "${ROOT}" + +# create a temporary directory +TMP_DIR=$(mktemp -d) + +# cleanup +exitHandler() ( + echo "Cleaning up..." + rm -rf "${TMP_DIR}" +) +trap exitHandler EXIT + +# Perform go install in a temp dir as we are not tracking this version in a go +# module. +# If we do the go install in the repo, it will create/update go.mod and go.sum. +cd "${TMP_DIR}" +GO111MODULE=on GOBIN="${TMP_DIR}" go install "sigs.k8s.io/mdtoc@${TOOL_VERSION}" +export PATH="${TMP_DIR}:${PATH}" +cd "${ROOT}" + +# Update tables of contents if necessary. +find keps -name '*.md' \ + | grep -Fxvf hack/.notableofcontents \ + | xargs mdtoc --inplace --max-depth=5 || ( + echo "Failed generating TOC. If this failed silently and you are on mac, try 'brew install grep'" + exit 1 + ) diff --git a/hack/verify-toc.sh b/hack/verify-toc.sh new file mode 100755 index 000000000000..e052a0192d76 --- /dev/null +++ b/hack/verify-toc.sh @@ -0,0 +1,52 @@ +#!/usr/bin/env bash + +# Copyright 2022 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 + +# keep in sync with hack/update-toc.sh +TOOL_VERSION=b8c54a57d69f29386d055584e595f38d65ce2a1f + +# cd to the root path +ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd -P)" +cd "${ROOT}" + +# create a temporary directory +TMP_DIR=$(mktemp -d) + +# cleanup +exitHandler() ( + echo "Cleaning up..." + rm -rf "${TMP_DIR}" +) +trap exitHandler EXIT + +# perform go install in a temp dir as we are not tracking this version in a go module +# if we do the go install in the repo, it will create / update a go.mod and go.sum +cd "${TMP_DIR}" +GO111MODULE=on GOBIN="${TMP_DIR}" go install "sigs.k8s.io/mdtoc@${TOOL_VERSION}" +export PATH="${TMP_DIR}:${PATH}" +cd "${ROOT}" + +echo "Checking table of contents are up to date..." +# Verify tables of contents are up-to-date +find keps -name '*.md' \ + | grep -Fxvf hack/.notableofcontents \ + | xargs mdtoc --inplace --max-depth=5 --dryrun || ( + echo "Table of content not up to date. If this failed silently and you are on mac, try 'brew install grep'" + exit 1 + ) diff --git a/keps/NNNN-template/README.md b/keps/NNNN-template/README.md new file mode 100644 index 000000000000..d3c53d0b1897 --- /dev/null +++ b/keps/NNNN-template/README.md @@ -0,0 +1,246 @@ +# KEP-NNNN: Your short, descriptive title + + + + + + +- [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) + - [Notes/Contraints/Caveats (Optional)](#notescontraintscaveats-optional) + - [Risks and Mitigations](#risks-and-mitigations) +- [Design Details](#design-details) + - [Test Plan](#test-plan) + - [Prerequisite testing updates](#prerequisite-testing-updates) + - [Unit Tests](#unit-tests) + - [Integration tests](#integration-tests) + - [Graduation Criteria](#graduation-criteria) +- [Implementation History](#implementation-history) +- [Drawbacks](#drawbacks) +- [Alternatives](#alternatives) + + +## Summary + + + +## Motivation + + + +### Goals + + + +### Non-Goals + + + +## Proposal + + + +### User Stories (Optional) + + + +#### Story 1 + +#### Story 2 + +### Notes/Contraints/Caveats (Optional) + + + +### Risks and Mitigations + + + +## Design Details + + + +### Test Plan + + + +[ ] I/we understand the owners of the involved components may require updates to +existing tests to make this code solid enough prior to committing the changes necessary +to implement this enhancement. + +##### Prerequisite testing updates + + + +#### Unit Tests + + + + + +- ``: `` - `` + +#### Integration tests + + + +### Graduation Criteria + + + +## Implementation History + + + +## Drawbacks + + + +## Alternatives + + diff --git a/keps/NNNN-template/kep.yaml b/keps/NNNN-template/kep.yaml new file mode 100644 index 000000000000..0b6abad17490 --- /dev/null +++ b/keps/NNNN-template/kep.yaml @@ -0,0 +1,42 @@ +title: KEP Template +kep-number: NNNN +authors: + - "@jane.doe" +status: provisional|implementable|implemented|deferred|rejected|withdrawn|replaced +creation-date: yyyy-mm-dd +reviewers: + - TBD + - "@alice.doe" +approvers: + - TBD + - "@oscar.doe" + +see-also: + - "/keps/1234-we-heard-you-like-keps" + - "/keps/2345-everyone-gets-a-kep" +replaces: + - "/keps/3456-replaced-kep" + +# The target maturity stage in the current dev cycle for this KEP. +stage: alpha|beta|stable + +# The most recent milestone for which work toward delivery of this KEP has been +# done. This can be the current (upcoming) milestone, if it is being actively +# worked on. +latest-milestone: "v0.2" + +# The milestone at which this feature was, or is targeted to be, at each stage. +milestone: + alpha: "v0.2" + beta: "v0.3" + stable: "v0.5" + +# The following PRR answers are required at alpha release +# List the feature gate name and the components for which it must be enabled +feature-gates: + - name: MyFeature +disable-supported: true + +# The following PRR answers are required at beta release +metrics: + - my_feature_metric