From 2ac8400cb2f584d2892a7473a82196e5ac93059e Mon Sep 17 00:00:00 2001 From: Brian Grant Date: Thu, 20 Nov 2014 00:05:55 +0000 Subject: [PATCH] Add API documentation pre-commit hook. --- .travis.yml | 1 + hack/verify-description.sh | 47 +++++++++++++++++++++++++++++++++++++ hooks/description.sh | 26 +++++++++++++++++++++ hooks/prepare-commit-msg | 48 +++++++++++++++++++++++++++++--------- 4 files changed, 111 insertions(+), 11 deletions(-) create mode 100755 hack/verify-description.sh create mode 100755 hooks/description.sh diff --git a/.travis.yml b/.travis.yml index f57267d9acbcc..ea6fc3cec990a 100644 --- a/.travis.yml +++ b/.travis.yml @@ -9,6 +9,7 @@ install: - ./hack/travis/install-etcd.sh - ./hack/verify-gofmt.sh - ./hack/verify-boilerplate.sh + - ./hack/verify-description.sh - ./hack/travis/install-std-race.sh - ./hack/build-go.sh - go get ./contrib/podex diff --git a/hack/verify-description.sh b/hack/verify-description.sh new file mode 100755 index 0000000000000..ff55a77a4eb59 --- /dev/null +++ b/hack/verify-description.sh @@ -0,0 +1,47 @@ +#!/bin/bash + +# Copyright 2014 Google Inc. All rights reserved. +# +# 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 + +KUBE_ROOT=$(dirname "${BASH_SOURCE}")/.. + +cd "${KUBE_ROOT}" + +result=0 + +find_files() { + find . -not \( \ + \( \ + -wholename './output' \ + -o -wholename './_output' \ + -o -wholename './release' \ + -o -wholename './target' \ + -o -wholename '*/third_party/*' \ + -o -wholename '*/Godeps/*' \ + \) -prune \ + \) -name '*.go' +} + +find_files | egrep "pkg/api/v.[^/]*/types\.go" | grep -v v1beta3 | while read file ; do + if [[ "$("${KUBE_ROOT}/hooks/description.sh" "${file}")" -eq "0" ]]; then + echo "API file is missing the required field descriptions: ${file}" + result=1 + fi +done + +exit ${result} diff --git a/hooks/description.sh b/hooks/description.sh new file mode 100755 index 0000000000000..60efe26e28a09 --- /dev/null +++ b/hooks/description.sh @@ -0,0 +1,26 @@ +#!/bin/bash + +# Copyright 2014 Google Inc. All rights reserved. +# +# 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. + +# Print 1 if the file in $1 is not in need of additional field descriptions, 0 otherwise. +FILE="$1" + +if grep json: "${FILE}" | grep -v ,inline | grep -v -q description: ; then + echo "0" +else + echo "1" +fi +exit 0 + diff --git a/hooks/prepare-commit-msg b/hooks/prepare-commit-msg index f62396c9d022d..270fcd8585262 100755 --- a/hooks/prepare-commit-msg +++ b/hooks/prepare-commit-msg @@ -2,37 +2,48 @@ KUBE_HOOKS_DIR="$(dirname "$(test -L "$0" && echo "$(dirname $0)/$(readlink "$0")" || echo "$0")")" -files_need_gofmt="" -files_need_boilerplate="" +files_need_gofmt=() +files_need_boilerplate=() +files_need_description=() for file in $(git diff --cached --name-only --diff-filter ACM | grep "\.go" | grep -v -e "third_party" -e "Godeps"); do # Check for files that fail gofmt. diff="$(git show ":${file}" | gofmt -s -d)" if [[ -n "$diff" ]]; then - files_need_gofmt="${files_need_gofmt} ${file}" + files_need_gofmt+=("${file}") fi # Check for files without the required boilerplate. - boilerplate="$(${KUBE_HOOKS_DIR}/boilerplate.sh ${file})" + boilerplate=$("${KUBE_HOOKS_DIR}/boilerplate.sh" "${file}") if [[ "$boilerplate" -eq "0" ]]; then - files_need_boilerplate="${files_need_boilerplate} ${file}" + files_need_boilerplate+=("${file}") fi done # Check sh files for boilerplate for file in $(git diff --cached --name-only --diff-filter ACM | grep "\.sh" | grep -v "third_party"); do # Check for files without the required boilerplate. - boilerplate="$(${KUBE_HOOKS_DIR}/boilerplate.sh ${file})" + boilerplate=$("${KUBE_HOOKS_DIR}/boilerplate.sh" "${file}") if [[ "$boilerplate" -eq "0" ]]; then - files_need_boilerplate="${files_need_boilerplate} ${file}" + files_need_boilerplate+=("${file}") fi done -if [[ -n "${files_need_gofmt}" ]]; then +# Check API schema definitions for field descriptions +# TODO: Check v1beta3, once it is documented +for file in $(git diff --cached --name-only --diff-filter ACM | egrep "pkg/api/v.[^/]*/types\.go" | grep -v "third_party" | grep -v v1beta3); do + # Check for files with fields without description tags + descriptionless=$("${KUBE_HOOKS_DIR}/description.sh" "${file}") + if [[ "$descriptionless" -eq "0" ]]; then + files_need_description+=("${file}") + fi +done + +if [[ "${#files_need_gofmt[@]}" -ne 0 ]]; then ( echo echo "# *** ERROR: *** Some files have not been gofmt'd. To fix these" echo "# errors, run gofmt -s -w , or cut and paste the following:" - echo "# gofmt -s -w ${files_need_gofmt}" + echo "# gofmt -s -w ${files_need_gofmt[@]}" echo "#" echo "# Your commit will be aborted unless you override this warning. To" echo "# commit in spite of these format errors, delete the following line:" @@ -40,12 +51,12 @@ if [[ -n "${files_need_gofmt}" ]]; then ) >> $1 fi -if [[ -n "${files_need_boilerplate}" ]]; then +if [[ "${#files_need_boilerplate[@]}" -ne 0 ]]; then ( echo echo "# *** ERROR: *** Some files are missing the required boilerplate" echo "# header from hooks/boilerplate.txt:" - for file in ${files_need_boilerplate}; do + for file in "${files_need_boilerplate[@]}"; do echo "# ${file}" done echo "#" @@ -54,3 +65,18 @@ if [[ -n "${files_need_boilerplate}" ]]; then echo ) >> $1 fi + +if [[ "${#files_need_description[@]}" -ne 0 ]]; then + ( + echo + echo "# *** ERROR: *** Some API files are missing the required field descriptions" + echo "# Add description tags to all non-inline fields in the following files:" + for file in "${files_need_description[@]}"; do + echo "# ${file}" + done + echo "#" + echo "# Your commit will be aborted unless you fix these." + echo "# COMMIT_BLOCKED_ON_DESCRIPTION" + echo + ) >> $1 +fi