Add version bootstrap tool subcommand, for capability checking (#129)

This expands on #128 to add another bootstrap tool subcommand: `bootstrap-version`. This is designed to just be a simple number that's bumped whenever there's a feature scripts might need to query for. The version number is also automatically checked against the (numeric) value of the `PANTS_BOOTSTRAP_TOOLS` key.

For instance, suppose the bootstrap tools already existed (at version 1), and then `bootstrap-cache-key` command was added, the version number would be bumped to 2, and then a consumer (such as pantsbuild/actions#6) could run something like:

```shell
PANTS_BOOTSTRAP_CACHE_KEY=$(PANTS_BOOTSTRAP_TOOLS=2 ./pants bootstrap-cache-key)
```

Author: huonw

pants

@@ -12,6 +12,10 @@
 
 set -eou pipefail
 
+# an arbitrary number: bump when there's a change that someone might want to query for
+# (e.g. checking $(PANTS_BOOTSTRAP_TOOLS=1 ./pants version) >= ...)
+SCRIPT_VERSION=1
+
 # Source any custom bootstrap settings for Pants from PANTS_BOOTSTRAP if it exists.
 : ${PANTS_BOOTSTRAP:=".pants.bootstrap"}
 if [[ -f "${PANTS_BOOTSTRAP}" ]]; then
@@ -64,6 +68,8 @@ COLOR_GREEN="\x1b[32m"
 COLOR_YELLOW="\x1b[33m"
 COLOR_RESET="\x1b[0m"
 
+INSTALL_URL="https://www.pantsbuild.org/docs/installation"
+
 function log() {
   echo -e "$@" 1>&2
 }
@@ -140,7 +146,7 @@ function determine_pants_version {
   if [[ -z "${pants_version}" ]]; then
     die "Please explicitly specify the \`pants_version\` in your \`pants.toml\` under the \`[GLOBAL]\` scope.
 See https://pypi.org/project/pantsbuild.pants/#history for all released versions
-and https://www.pantsbuild.org/docs/installation for more instructions."
+and ${INSTALL_URL} for more instructions."
   fi
   pants_major_version="$(echo "${pants_version}" | cut -d '.' -f1)"
   pants_minor_version="$(echo "${pants_version}" | cut -d '.' -f2)"
@@ -389,6 +395,10 @@ function bootstrap_pants {
 
 function run_bootstrap_tools {
   # functionality for introspecting the bootstrapping process, without actually doing it
+  if [[ "${PANTS_BOOTSTRAP_TOOLS}" -gt "${SCRIPT_VERSION}" ]]; then
+      die "$0 script (bootstrap version ${SCRIPT_VERSION}) is too old for this invocation (with PANTS_BOOTSTRAP_TOOLS=${PANTS_BOOTSTRAP_TOOLS}).
+Please update it by following ${INSTALL_URL}"
+  fi
 
   case "${1:-}" in
     bootstrap-cache-key)
@@ -417,21 +427,38 @@ function run_bootstrap_tools {
       )
       echo "${parts[*]}"
       ;;
+    bootstrap-version)
+      echo "${SCRIPT_VERSION}"
+      ;;
     help|"")
       cat <<EOF
 Usage: PANTS_BOOTSTRAP_TOOLS=1 $0 ...
 
 Subcommands:
   bootstrap-cache-key
-    print an opaque that can be used as a key for accurate and safe caching of the pants bootstrap directories
+    Print an opaque that can be used as a key for accurate and safe caching of
+    the pants bootstrap directories.
+
+    (Added in bootstrap version 1.)
+
+  bootstrap-version
+    Print a version number for the bootstrap script itself.
+
+    Distributed scripts (such as reusable CI formulae) that use these bootstrap
+    tools should set PANTS_BOOTSTRAP_TOOLS to the minimum script version for the
+    features they require. For example, if 'some-tool' was added in version 123:
+
+        PANTS_BOOTSTRAP_TOOLS=123 ./pants some-tool
+
+    (Added in bootstrap version 1.)
 EOF
       ;;
     *)
-      die "Unknown subcommand for bootstrap tools (due to PANTS_BOOTSTRAP_TOOLS=1): $1 "
+      die "Unknown subcommand for bootstrap tools: $1. Do you mean to run without PANTS_BOOTSTRAP_TOOLS=1? Or, update this script ($INSTALL_URL)?"
   esac
 }
 
-if [[ "${PANTS_BOOTSTRAP_TOOLS:-}" = 1 ]]; then
+if [[ "${PANTS_BOOTSTRAP_TOOLS:-}" -gt 0 ]]; then
     run_bootstrap_tools "$@"
     exit 0
 fi

tests/test_smoke_tests.py

@@ -300,3 +300,18 @@ def test_python_alias(checker: SmokeTester) -> None:
         alias="python",
         bad_aliases={"python3.7": "35", "python3": "27"},
     )
+
+
+def test_bootstrap_tools_version_checking(checker: SmokeTester) -> None:
+    result = subprocess.run(
+        ["./pants", "bootstrap-version"],
+        check=False,
+        cwd=str(checker.build_root),
+        env={**os.environ, "PANTS_BOOTSTRAP_TOOLS": "987654321"},
+        capture_output=True,
+        text=True,
+    )
+    assert result.returncode == 1
+
+    assert result.stdout == ""
+    assert "is too old for this invocation (with PANTS_BOOTSTRAP_TOOLS=987654321)" in result.stderr