Add Documentation for Supported Bazel Versions (grpc#29191)

gnossen · web-flow · commit e79b2a9b32a0 · 2022-03-25T10:45:06.000-07:00
* Create Bazel support range docs

* Review comments

* Move supported versions file
diff --git a/bazel/supported_versions.txt b/bazel/supported_versions.txt
@@ -0,0 +1,3 @@
+5.0.0
+4.2.2
+3.7.2
diff --git a/doc/bazel_support.md b/doc/bazel_support.md
@@ -0,0 +1,44 @@
+# Bazel Support
+
+## Basic Usage
+
+The `grpc/grpc` repository's primary build system is Bazel. Rules are provided
+for C++, Python, and Objective-C. While C++ supports other build systems such as
+CMake, these rules are actually generated from the Bazel definitions.
+
+Projects built with Bazel may use the `grpc/grpc` repo not only to add a
+dependency on the library itself, but also to generate protobuf, stub, and
+servicer code. To do so, one must invoke the `grpc_deps` and `grpc_extra_deps`
+repository rules in their `WORKSPACE` file:
+
+```starlark
+workspace(name = "example_workspace")
+
+load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
+
+http_archive(
+    name = "com_github_grpc_grpc",
+    strip_prefix = "grpc-1.45.0",
+    sha256 = "ec19657a677d49af59aa806ec299c070c882986c9fcc022b1c22c2a3caf01bcd"k
+    urls = ["https://github.com/grpc/grpc/archive/refs/tags/v1.45.0.tar.gz"],
+)
+
+load("@com_github_grpc_grpc//bazel:grpc_deps.bzl", "grpc_deps")
+
+grpc_deps()
+
+load("@com_github_grpc_grpc//bazel:grpc_extra_deps.bzl", "grpc_extra_deps")
+
+grpc_extra_deps()
+```
+
+## Supported Versions
+
+In general, gRPC supports building with the latest patch release of the most
+recent two major versions of Bazel. However individual releases may have a
+broader compatibility range. The currently supported versions are captured by
+the following list:
+
+- [`5.0.0`](https://github.com/bazelbuild/bazel/releases/tag/5.0.0)
+- [`4.2.2`](https://github.com/bazelbuild/bazel/releases/tag/4.2.2)
+- [`3.7.2`](https://github.com/bazelbuild/bazel/releases/tag/3.7.2)
diff --git a/templates/doc/bazel_support.md.template b/templates/doc/bazel_support.md.template
@@ -0,0 +1,46 @@
+%YAML 1.2
+--- |
+  # Bazel Support
+  
+  ${ '##' } Basic Usage
+  
+  The `grpc/grpc` repository's primary build system is Bazel. Rules are provided
+  for C++, Python, and Objective-C. While C++ supports other build systems such as
+  CMake, these rules are actually generated from the Bazel definitions.
+  
+  Projects built with Bazel may use the `grpc/grpc` repo not only to add a
+  dependency on the library itself, but also to generate protobuf, stub, and
+  servicer code. To do so, one must invoke the `grpc_deps` and `grpc_extra_deps`
+  repository rules in their `WORKSPACE` file:
+  
+  ```starlark
+  workspace(name = "example_workspace")
+  
+  load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
+  
+  http_archive(
+      name = "com_github_grpc_grpc",
+      strip_prefix = "grpc-1.45.0",
+      sha256 = "ec19657a677d49af59aa806ec299c070c882986c9fcc022b1c22c2a3caf01bcd"k
+      urls = ["https://github.com/grpc/grpc/archive/refs/tags/v1.45.0.tar.gz"],
+  )
+  
+  load("@com_github_grpc_grpc//bazel:grpc_deps.bzl", "grpc_deps")
+  
+  grpc_deps()
+  
+  load("@com_github_grpc_grpc//bazel:grpc_extra_deps.bzl", "grpc_extra_deps")
+  
+  grpc_extra_deps()
+  ```
+  
+  ${ '##' } Supported Versions
+  
+  In general, gRPC supports building with the latest patch release of the most
+  recent two major versions of Bazel. However individual releases may have a
+  broader compatibility range. The currently supported versions are captured by
+  the following list:
+
+  % for version in supported_bazel_versions:
+  - [`${version}`](https://github.com/bazelbuild/bazel/releases/tag/${version})
+  % endfor
diff --git a/test/distrib/bazel/run_bazel_distrib_test.sh b/test/distrib/bazel/run_bazel_distrib_test.sh
@@ -18,14 +18,10 @@ set -ex
 cd "$(dirname "$0")"
 
 # TODO(jtattermusch): make build work with bazel 2.2.0 and bazel 1.2.1 if that's reasonably simple.
-SUPPORTED_VERSIONS=(
-  "3.7.2"
-  "4.0.0"
-  "5.0.0"
-)
+VERSIONS=$(cat ../../../bazel/supported_versions.txt)
 
 FAILED_VERSIONS=""
-for VERSION in "${SUPPORTED_VERSIONS[@]}"; do
+for VERSION in $VERSIONS; do
     echo "Running bazel distribtest with bazel version ${VERSION}"
     ./test_single_bazel_version.sh "${VERSION}" || FAILED_VERSIONS="${FAILED_VERSIONS}${VERSION} "
 done
diff --git a/tools/buildgen/plugins/supported_bazel_versions.py b/tools/buildgen/plugins/supported_bazel_versions.py
@@ -0,0 +1,28 @@
+# Copyright 2022 The gRPC 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.
+"""Retrieves supported bazel versions from plaintext file."""
+
+_SUPPORTED_VERSIONS_FILE = "bazel/supported_versions.txt"
+
+
+def _get_supported_bazel_versions():
+    versions = []
+    with open(_SUPPORTED_VERSIONS_FILE, "r") as f:
+        for line in f:
+            versions.append(line.strip())
+    return versions
+
+
+def mako_plugin(dictionary):
+    dictionary["supported_bazel_versions"] = _get_supported_bazel_versions()
diff --git a/tools/doxygen/Doxyfile.c++ b/tools/doxygen/Doxyfile.c++
@@ -762,6 +762,7 @@ WARN_LOGFILE           =
 
 INPUT                  = doc/PROTOCOL-HTTP2.md \
 doc/PROTOCOL-WEB.md \
+doc/bazel_support.md \
 doc/binary-logging.md \
 doc/c-style-guide.md \
 doc/command_line_tool.md \
diff --git a/tools/doxygen/Doxyfile.c++.internal b/tools/doxygen/Doxyfile.c++.internal
diff --git a/tools/doxygen/Doxyfile.core b/tools/doxygen/Doxyfile.core
@@ -762,6 +762,7 @@ WARN_LOGFILE           =
 
 INPUT                  = doc/PROTOCOL-HTTP2.md \
 doc/PROTOCOL-WEB.md \
+doc/bazel_support.md \
 doc/binary-logging.md \
 doc/c-style-guide.md \
 doc/command_line_tool.md \
diff --git a/tools/doxygen/Doxyfile.core.internal b/tools/doxygen/Doxyfile.core.internal
diff --git a/tools/doxygen/Doxyfile.objc b/tools/doxygen/Doxyfile.objc
@@ -762,6 +762,7 @@ WARN_LOGFILE           =
 
 INPUT                  = doc/PROTOCOL-HTTP2.md \
 doc/PROTOCOL-WEB.md \
+doc/bazel_support.md \
 doc/binary-logging.md \
 doc/c-style-guide.md \
 doc/command_line_tool.md \
diff --git a/tools/doxygen/Doxyfile.objc.internal b/tools/doxygen/Doxyfile.objc.internal
@@ -762,6 +762,7 @@ WARN_LOGFILE           =
 
 INPUT                  = doc/PROTOCOL-HTTP2.md \
 doc/PROTOCOL-WEB.md \
+doc/bazel_support.md \
 doc/binary-logging.md \
 doc/c-style-guide.md \
 doc/command_line_tool.md \
diff --git a/tools/doxygen/Doxyfile.php b/tools/doxygen/Doxyfile.php
@@ -762,6 +762,7 @@
 
 INPUT                  = doc/PROTOCOL-HTTP2.md \
 doc/PROTOCOL-WEB.md \
+doc/bazel_support.md \
 doc/binary-logging.md \
 doc/c-style-guide.md \
 doc/command_line_tool.md \
diff --git a/tools/release/update_supported_bazel_versions.sh b/tools/release/update_supported_bazel_versions.sh
@@ -0,0 +1,46 @@
+#!/bin/bash
+#Copyright 2022 The gRPC 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.
+
+# This script can be used to manually update the specific versions of Bazel
+# tested by the Bazel distribtests and advertised as supported in documentation.
+# This will update the supported_versions.txt file, which will be templated into
+# the bazel_support.md document.
+
+# This script selects the latest patch release of the two most recent major
+# versions of Bazel. If you want to include other versions in the set of
+# supported versions, then you will need to manually edit the ifle.
+
+set -xeuo pipefail
+
+cd "$(dirname "$0")/../.."
+
+# The number of most recent supported major Bazel versions.
+SUPPORT_RANGE="2"
+
+# Retrieve all git tags from the Bazel git repo.
+TAGS=$(git ls-remote --tags git@github.com:bazelbuild/bazel.git | awk '{print $2;}' | sed 's|refs/tags/||g')
+
+# Find the n most recent major versions.
+MAJOR_VERSIONS=$(echo "$TAGS" | egrep '^[0-9]+\.[0-9]+\.[0-9]+$' | cut -d'.' -f1 | sort -r | uniq | head -n"$SUPPORT_RANGE")
+
+SUPPORTED_VERSIONS=""
+
+# For each major version selected, find the most recent patch release.
+while read -r MAJOR_VERSION; do
+  LATEST_PATCH=$(echo "$TAGS" | egrep "^${MAJOR_VERSION}\.[0-9]+\.[0-9]+$" | sort -nr | head -n1)
+  SUPPORTED_VERSIONS="$SUPPORTED_VERSIONS$LATEST_PATCH\n"
+done<<<"$MAJOR_VERSIONS"
+
+printf "$SUPPORTED_VERSIONS" | tee bazel/supported_versions.txt
