api/tools: some progress towards generalizing API version upgrade. (#10507)

* Automatically derive active protos target used in proto_format.sh from the packages with files
  annotated as active.

* Replace some sites with hardcoded v2/v3 with active/next_major_version_candidate.

* Move //docs:BUILD to //versioning:BUILD in API tree. This has already ceased to be used directly
  in the docs build, so this makes things a bit clearer.

Risk level: Low (API tooling and build only)
Testing: fix_format (mostly idempotent)

Part of #10355.

Signed-off-by: Harvey Tuch <htuch@google.com>

Mirrored from https://github.com/envoyproxy/envoy @ 4403003b9c0888ce81606a2f45fcc1da126514e7

CONTRIBUTING.md

@@ -9,7 +9,7 @@ changes. They may be as part of a larger implementation PR. Please follow the st
 process for validating build/test sanity of `api/` before submitting a PR.
 
 *Note: New .proto files should be added to
-[BUILD](https://github.com/envoyproxy/envoy/blob/master/api/docs/BUILD) in order to get the RSTs generated.*
+[BUILD](https://github.com/envoyproxy/envoy/blob/master/api/versioning/BUILD) in order to get the RSTs generated.*
 
 ## Documentation changes
 

STYLE.md

@@ -140,7 +140,7 @@ To add an extension config to the API, the steps below should be followed:
    This places the filter in the correct [v3 package hierarchy](#package-organization).
 1. If this is still WiP and subject to breaking changes, import
    `udpa/annotations/status.proto` and set `option (udpa.annotations.file_status).work_in_progress = true;`.
-1. Add a reference to the v2 extension config in (1) in [api/docs/BUILD](docs/BUILD).
+1. Add a reference to the v2 extension config in (1) in [api/versioning/BUILD](versioning/BUILD).
 1. Run `./tools/proto_format/proto_format.sh fix`. This should regenerate the `BUILD` file,
    reformat `foobar.proto` as needed and also generate the v3 extension config,
    together with shadow API protos.

versioning/BUILD

@@ -1,17 +1,12 @@
+# DO NOT EDIT. This file is generated by tools/proto_format/active_protos_gen.py.
+
 licenses(["notice"])  # Apache 2
 
 load("@rules_proto//proto:defs.bzl", "proto_library")
 
-package_group(
-    name = "docs",
-    packages = [
-        "//docs",
-    ],
-)
-
-# This is where you add protos that will participate in docs RST generation.
+# This track active development versions of protos.
 proto_library(
-    name = "protos",
+    name = "active_protos",
     visibility = ["//visibility:public"],
     deps = [
         "//envoy/admin/v2alpha:pkg",