Add API documentation pre-commit hook.

This commit is contained in:
Brian Grant 2014-11-20 00:05:55 +00:00
parent 57ec3a720b
commit 2ac8400cb2
4 changed files with 111 additions and 11 deletions

View File

@ -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

47
hack/verify-description.sh Executable file
View File

@ -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}

26
hooks/description.sh Executable file
View File

@ -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

View File

@ -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 <file>, 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