From a739d22015568ec982ff658fa81c65a1269fe6eb Mon Sep 17 00:00:00 2001 From: Ricky Stewart Date: Tue, 10 Dec 2024 21:09:23 +0000 Subject: [PATCH] ci: check that generated documentation is up-to-date Since `release-24.1`, CI has been missing a set of checks that ensure the generated documentation files are configured correctly with respect to `BUILD.bazel` and the checked-in files. Here we add them back in and fix the skew that has already been introduced. Closes: #137133 Epic: none Release note: None --- build/github/build.sh | 56 +++++++++++++++++++ docs/generated/sql/bnf/BUILD.bazel | 1 + .../sql/bnf/cancel_all_jobs_stmt.bnf | 2 - .../sql/bnf/resume_all_jobs_stmt.bnf | 2 - .../sql/bnf/set_transaction_stmt.bnf | 3 - pkg/gen/bnf.bzl | 1 + pkg/gen/diagrams.bzl | 1 + pkg/gen/docs.bzl | 1 + 8 files changed, 60 insertions(+), 7 deletions(-) delete mode 100644 docs/generated/sql/bnf/cancel_all_jobs_stmt.bnf delete mode 100644 docs/generated/sql/bnf/resume_all_jobs_stmt.bnf delete mode 100644 docs/generated/sql/bnf/set_transaction_stmt.bnf diff --git a/build/github/build.sh b/build/github/build.sh index 71d57a35d6cb..6c08f4baaecc 100755 --- a/build/github/build.sh +++ b/build/github/build.sh @@ -48,3 +48,59 @@ bazel build \ //pkg/cmd/cockroach-short //pkg/cmd/cockroach \ //pkg/cmd/cockroach-sql $GEOS_TARGET $EXTRA_TARGETS +# We don't have to exercise the checks below on every configuration, only +# bother with Linux. +if [ "$CONFIG" != "crosslinux" ] +then + exit 0 +fi + +# This is going to be very noisy if we don't disbale this logging. +set +x +BAZEL_BIN=$(bazel info bazel-bin --config "$CONFIG") +FAILED= +# Ensure all generated docs are byte-for-byte identical with the checkout. +for FILE in $(find $BAZEL_BIN/docs -type f) +do + RESULT=$(diff $FILE ${FILE##$BAZEL_BIN/}) + if [[ ! $? -eq 0 ]] + then + echo "File $FILE does not match with checked-in version. Got diff:" + echo "$RESULT" + echo "Run './dev generate docs'" + FAILED=1 + fi +done +# Ensure the generated docs are inclusive of what we have in tree: list all +# generated files in a few subdirectories and make sure they're all in the +# build output. +for FILE in $(ls docs/generated/http/*.md | xargs -n1 basename) +do + if [[ ! -f $BAZEL_BIN/docs/generated/http/$FILE ]] + then + echo "File $BAZEL_BIN/docs/generated/http/$FILE does not exist as a generated artifact; it is checked in under `docs/generated/http`, but is not being built. Is docs/generated/http/BUILD.bazel up-to-date?" + FAILED=1 + fi +done +for FILE in $(ls docs/generated/sql/*.md | xargs -n1 basename) +do + if [[ ! -f $BAZEL_BIN/docs/generated/sql/$FILE ]] + then + echo "File $BAZEL_BIN/docs/generated/sql/$FILE does not exist as a generated artifact; it is checked in under `docs/generated/sql`, but is not being built. Is docs/generated/sql/BUILD.bazel up-to-date?" + FAILED=1 + fi +done +for FILE in $(ls docs/generated/sql/bnf/*.bnf | xargs -n1 basename) +do + if [[ ! -f $BAZEL_BIN/docs/generated/sql/bnf/$FILE ]] + then + echo "File $BAZEL_BIN/docs/generated/sql/bnf/$FILE does not exist as a generated artifact; it is checked in under `docs/generated/sql/bnf`, but is not being built. Is docs/generated/sql/bnf/BUILD.bazel up-to-date?" + FAILED=1 + fi +done + +if [[ ! -z "$FAILED" ]] +then + echo 'Generated files do not match! Are the checked-in generated files up-to-date?' + exit 1 +fi diff --git a/docs/generated/sql/bnf/BUILD.bazel b/docs/generated/sql/bnf/BUILD.bazel index 2c6e83df486c..2dfd2d261ae7 100644 --- a/docs/generated/sql/bnf/BUILD.bazel +++ b/docs/generated/sql/bnf/BUILD.bazel @@ -73,6 +73,7 @@ FILES = [ "backup", "backup_options", "begin_transaction", + "begin_stmt", "call", "cancel_all_jobs", "cancel_job", diff --git a/docs/generated/sql/bnf/cancel_all_jobs_stmt.bnf b/docs/generated/sql/bnf/cancel_all_jobs_stmt.bnf deleted file mode 100644 index c313389569f0..000000000000 --- a/docs/generated/sql/bnf/cancel_all_jobs_stmt.bnf +++ /dev/null @@ -1,2 +0,0 @@ -cancel_all_jobs_stmt ::= - 'CANCEL' 'ALL' name 'JOBS' diff --git a/docs/generated/sql/bnf/resume_all_jobs_stmt.bnf b/docs/generated/sql/bnf/resume_all_jobs_stmt.bnf deleted file mode 100644 index b17d76fde0b7..000000000000 --- a/docs/generated/sql/bnf/resume_all_jobs_stmt.bnf +++ /dev/null @@ -1,2 +0,0 @@ -resume_all_jobs_stmt ::= - 'RESUME' 'ALL' name 'JOBS' diff --git a/docs/generated/sql/bnf/set_transaction_stmt.bnf b/docs/generated/sql/bnf/set_transaction_stmt.bnf deleted file mode 100644 index 3ce95cb05c13..000000000000 --- a/docs/generated/sql/bnf/set_transaction_stmt.bnf +++ /dev/null @@ -1,3 +0,0 @@ -set_transaction_stmt ::= - 'SET' 'TRANSACTION' transaction_mode_list - | 'SET' 'SESSION' 'TRANSACTION' transaction_mode_list diff --git a/pkg/gen/bnf.bzl b/pkg/gen/bnf.bzl index 0d5a443132c3..077ead825fd7 100644 --- a/pkg/gen/bnf.bzl +++ b/pkg/gen/bnf.bzl @@ -72,6 +72,7 @@ BNF_SRCS = [ "//docs/generated/sql/bnf:analyze_stmt.bnf", "//docs/generated/sql/bnf:backup.bnf", "//docs/generated/sql/bnf:backup_options.bnf", + "//docs/generated/sql/bnf:begin_stmt.bnf", "//docs/generated/sql/bnf:begin_transaction.bnf", "//docs/generated/sql/bnf:call.bnf", "//docs/generated/sql/bnf:cancel_all_jobs.bnf", diff --git a/pkg/gen/diagrams.bzl b/pkg/gen/diagrams.bzl index 3c38ec19a78b..c69698280ff0 100644 --- a/pkg/gen/diagrams.bzl +++ b/pkg/gen/diagrams.bzl @@ -72,6 +72,7 @@ DIAGRAMS_SRCS = [ "//docs/generated/sql/bnf:analyze.html", "//docs/generated/sql/bnf:backup.html", "//docs/generated/sql/bnf:backup_options.html", + "//docs/generated/sql/bnf:begin.html", "//docs/generated/sql/bnf:begin_transaction.html", "//docs/generated/sql/bnf:call.html", "//docs/generated/sql/bnf:cancel.html", diff --git a/pkg/gen/docs.bzl b/pkg/gen/docs.bzl index 1ea2b9064d38..5dc0cbeb0e48 100644 --- a/pkg/gen/docs.bzl +++ b/pkg/gen/docs.bzl @@ -85,6 +85,7 @@ DOCS_SRCS = [ "//docs/generated/sql/bnf:analyze_stmt.bnf", "//docs/generated/sql/bnf:backup.bnf", "//docs/generated/sql/bnf:backup_options.bnf", + "//docs/generated/sql/bnf:begin_stmt.bnf", "//docs/generated/sql/bnf:begin_transaction.bnf", "//docs/generated/sql/bnf:call.bnf", "//docs/generated/sql/bnf:cancel_all_jobs.bnf",