api: remove [:alpha] protodoc tag and replace with annotation (#18218)

This is a first step towards https://github.com/envoyproxy/envoy/issues/17920

A single proto (kafka mesh) has been swapped from using the udpa
file_status annotation to the xds file_status annotation to avoid a
large amount of churn and a forthcoming migration of many alpha/wip
protos to non alpha/wip. The rest will be audited and swapped in
future PRs. This single one was done to make sure the doc machinary
works properly.

Signed-off-by: Matt Klein <mklein@lyft.com>

Mirrored from https://github.com/envoyproxy/envoy @ f0f17a3caa75106a9e28b99edc27dd09c1bed488

API_VERSIONING.md

@@ -72,8 +72,10 @@ An exception to the above policy exists for:
 or message has not been included in an Envoy release.
 * API versions tagged `vNalpha`. Within an alpha major version, arbitrary breaking changes are allowed.
 * Any field, message or enum with a `[#not-implemented-hide:..` comment.
-* Any proto with a `(udpa.annotations.file_status).work_in_progress` option annotation.
-* Any proto marked as [#alpha:].
+* Any proto with a `(udpa.annotations.file_status).work_in_progress`,
+  `(xds.annotations.v3.file_status).work_in_progress`
+  `(xds.annotations.v3.message_status).work_in_progress`, or
+  `(xds.annotations.v3.field_status).work_in_progress` option annotation.
 
 Note that changes to default values for wrapped types, e.g. `google.protobuf.UInt32Value` are not
 governed by the above policy. Any management server requiring stability across Envoy API or

STYLE.md

@@ -34,10 +34,13 @@ In addition, the following conventions should be followed:
   implementation. These indicate that the entity is not implemented in Envoy and the entity
   should be hidden from the Envoy documentation.
 
-* Use a `[#alpha:]` annotation in comments for messages that are considered alpha
-  and are not subject to the threat model. This is similar to the work-in-progress/alpha tagging
-  of extensions described below, but allows tagging messages that are used as part of the core API
-  as alpha without having to break it into its own file.
+* Use a `(xds.annotations.v3.file_status).work_in_progress`,
+  `(xds.annotations.v3.message_status).work_in_progress`, or
+  `(xds.annotations.v3.field_status).work_in_progress` option annotation for files,
+  messages, or fields, respectively, that are considered work in progress and are not subject to the
+  threat model or the breaking change policy. This is similar to the work-in-progress/alpha tagging
+  of extensions described below, but allows tagging protos that are used as part of the core API
+  as work in progress without having to break them into their own file.
 
 * Always use plural field names for `repeated` fields, such as `filters`.
 

bazel/repository_locations.bzl

@@ -44,9 +44,9 @@ REPOSITORY_LOCATIONS_SPEC = dict(
         project_desc = "xDS API Working Group (xDS-WG)",
         project_url = "https://github.com/cncf/xds",
         # During the UDPA -> xDS migration, we aren't working with releases.
-        version = "dd25fe81a44506ab21ea666fb70b3b1c4bb183ee",
-        sha256 = "9184235cd31272679e4c7f9232c341d4ea75351ded74d3fbba28b05c290bfa71",
-        release_date = "2021-07-22",
+        version = "25de7278fc844d392d607214f36dbedf50f167ee",
+        sha256 = "4107d57fbfb0d1a20a191c4eac59579ec029242928ea0c75d0e42728380cf369",
+        release_date = "2021-09-22",
         strip_prefix = "xds-{version}",
         urls = ["https://github.com/cncf/xds/archive/{version}.tar.gz"],
         use_category = ["api"],

contrib/envoy/extensions/filters/network/kafka_mesh/v3alpha/BUILD

@@ -5,5 +5,8 @@ load("@envoy_api//bazel:api_build_system.bzl", "api_proto_package")
 licenses(["notice"])  # Apache 2
 
 api_proto_package(
-    deps = ["@com_github_cncf_udpa//udpa/annotations:pkg"],
+    deps = [
+        "@com_github_cncf_udpa//udpa/annotations:pkg",
+        "@com_github_cncf_udpa//xds/annotations/v3:pkg",
+    ],
 )

contrib/envoy/extensions/filters/network/kafka_mesh/v3alpha/kafka_mesh.proto

@@ -2,14 +2,16 @@ syntax = "proto3";
 
 package envoy.extensions.filters.network.kafka_mesh.v3alpha;
 
+import "xds/annotations/v3/status.proto";
+
 import "udpa/annotations/status.proto";
 import "validate/validate.proto";
 
 option java_package = "io.envoyproxy.envoy.extensions.filters.network.kafka_mesh.v3alpha";
 option java_outer_classname = "KafkaMeshProto";
 option java_multiple_files = true;
-option (udpa.annotations.file_status).work_in_progress = true;
 option (udpa.annotations.file_status).package_version_status = ACTIVE;
+option (xds.annotations.v3.file_status).work_in_progress = true;
 
 // [#protodoc-title: Kafka Mesh]
 // Kafka Mesh :ref:`configuration overview <config_network_filters_kafka_mesh>`.

envoy/config/common/key_value/v3/BUILD

@@ -8,5 +8,6 @@ api_proto_package(
     deps = [
         "//envoy/config/core/v3:pkg",
         "@com_github_cncf_udpa//udpa/annotations:pkg",
+        "@com_github_cncf_udpa//xds/annotations/v3:pkg",
     ],
 )

envoy/config/common/key_value/v3/config.proto

@@ -4,6 +4,8 @@ package envoy.config.common.key_value.v3;
 
 import "envoy/config/core/v3/extension.proto";
 
+import "xds/annotations/v3/status.proto";
+
 import "udpa/annotations/status.proto";
 import "validate/validate.proto";
 
@@ -14,9 +16,10 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE;
 
 // [#protodoc-title: Key Value Store storage plugin]
 
-// [#alpha:]
 // This shared configuration for Envoy key value stores.
 message KeyValueStoreConfig {
+  option (xds.annotations.v3.message_status).work_in_progress = true;
+
   // [#extension-category: envoy.common.key_value]
   core.v3.TypedExtensionConfig config = 1 [(validate.rules).message = {required: true}];
 }

envoy/config/common/matcher/v3/BUILD

@@ -10,5 +10,6 @@ api_proto_package(
         "//envoy/config/route/v3:pkg",
         "//envoy/type/matcher/v3:pkg",
         "@com_github_cncf_udpa//udpa/annotations:pkg",
+        "@com_github_cncf_udpa//xds/annotations/v3:pkg",
     ],
 )

envoy/config/common/matcher/v3/matcher.proto

@@ -6,6 +6,8 @@ import "envoy/config/core/v3/extension.proto";
 import "envoy/config/route/v3/route_components.proto";
 import "envoy/type/matcher/v3/string.proto";
 
+import "xds/annotations/v3/status.proto";
+
 import "udpa/annotations/status.proto";
 import "validate/validate.proto";
 
@@ -21,9 +23,9 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE;
 // is found the action specified by the most specific on_no_match will be evaluated.
 // As an on_no_match might result in another matching tree being evaluated, this process
 // might repeat several times until the final OnMatch (or no match) is decided.
-//
-// [#alpha:]
 message Matcher {
+  option (xds.annotations.v3.message_status).work_in_progress = true;
+
   // What to do if a match is successful.
   message OnMatch {
     oneof on_match {

envoy/config/core/v3/BUILD

@@ -11,6 +11,7 @@ api_proto_package(
         "//envoy/type/matcher/v3:pkg",
         "//envoy/type/v3:pkg",
         "@com_github_cncf_udpa//udpa/annotations:pkg",
+        "@com_github_cncf_udpa//xds/annotations/v3:pkg",
         "@com_github_cncf_udpa//xds/core/v3:pkg",
     ],
 )

envoy/config/core/v3/protocol.proto

@@ -8,6 +8,8 @@ import "envoy/type/v3/percent.proto";
 import "google/protobuf/duration.proto";
 import "google/protobuf/wrappers.proto";
 
+import "xds/annotations/v3/status.proto";
+
 import "envoy/annotations/deprecation.proto";
 import "udpa/annotations/status.proto";
 import "udpa/annotations/versioning.proto";
@@ -508,8 +510,8 @@ message Http3ProtocolOptions {
   // <https://datatracker.ietf.org/doc/html/rfc8441>`_
   // and settings `proposed for HTTP/3
   // <https://datatracker.ietf.org/doc/draft-ietf-httpbis-h3-websockets/>`_
-  // [#alpha:] as HTTP/3 CONNECT is not yet an RFC.
-  bool allow_extended_connect = 5;
+  // Note that HTTP/3 CONNECT is not yet an RFC.
+  bool allow_extended_connect = 5 [(xds.annotations.v3.field_status).work_in_progress = true];
 }
 
 // A message to control transformations to the :scheme header

envoy/extensions/common/matching/v3/BUILD

@@ -10,6 +10,7 @@ api_proto_package(
         "//envoy/config/common/matcher/v3:pkg",
         "//envoy/config/core/v3:pkg",
         "@com_github_cncf_udpa//udpa/annotations:pkg",
+        "@com_github_cncf_udpa//xds/annotations/v3:pkg",
         "@com_github_cncf_udpa//xds/type/matcher/v3:pkg",
     ],
 )

envoy/extensions/common/matching/v3/extension_matcher.proto

@@ -5,6 +5,7 @@ package envoy.extensions.common.matching.v3;
 import "envoy/config/common/matcher/v3/matcher.proto";
 import "envoy/config/core/v3/extension.proto";
 
+import "xds/annotations/v3/status.proto";
 import "xds/type/matcher/v3/matcher.proto";
 
 import "envoy/annotations/deprecation.proto";
@@ -21,9 +22,9 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE;
 // Wrapper around an existing extension that provides an associated matcher. This allows
 // decorating an existing extension with a matcher, which can be used to match against
 // relevant protocol data.
-//
-// [#alpha:]
 message ExtensionWithMatcher {
+  option (xds.annotations.v3.message_status).work_in_progress = true;
+
   // The associated matcher. This is deprecated in favor of xds_matcher.
   config.common.matcher.v3.Matcher matcher = 1
       [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"];

envoy/extensions/filters/http/composite/v3/BUILD

@@ -8,5 +8,6 @@ api_proto_package(
     deps = [
         "//envoy/config/core/v3:pkg",
         "@com_github_cncf_udpa//udpa/annotations:pkg",
+        "@com_github_cncf_udpa//xds/annotations/v3:pkg",
     ],
 )

envoy/extensions/filters/http/composite/v3/composite.proto

@@ -4,6 +4,8 @@ package envoy.extensions.filters.http.composite.v3;
 
 import "envoy/config/core/v3/extension.proto";
 
+import "xds/annotations/v3/status.proto";
+
 import "udpa/annotations/status.proto";
 
 option java_package = "io.envoyproxy.envoy.extensions.filters.http.composite.v3";
@@ -25,9 +27,8 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE;
 // where a match tree is specified that indicates (via
 // :ref:`ExecuteFilterAction <envoy_v3_api_msg_extensions.filters.http.composite.v3.ExecuteFilterAction>`)
 // which filter configuration to create and delegate to.
-//
-// [#alpha:]
 message Composite {
+  option (xds.annotations.v3.message_status).work_in_progress = true;
 }
 
 // Composite match action (see :ref:`matching docs <arch_overview_matching_api>` for more info on match actions).

envoy/extensions/key_value/file_based/v3/BUILD

@@ -5,5 +5,8 @@ load("@envoy_api//bazel:api_build_system.bzl", "api_proto_package")
 licenses(["notice"])  # Apache 2
 
 api_proto_package(
-    deps = ["@com_github_cncf_udpa//udpa/annotations:pkg"],
+    deps = [
+        "@com_github_cncf_udpa//udpa/annotations:pkg",
+        "@com_github_cncf_udpa//xds/annotations/v3:pkg",
+    ],
 )

envoy/extensions/key_value/file_based/v3/config.proto

@@ -4,6 +4,8 @@ package envoy.extensions.key_value.file_based.v3;
 
 import "google/protobuf/duration.proto";
 
+import "xds/annotations/v3/status.proto";
+
 import "udpa/annotations/status.proto";
 import "validate/validate.proto";
 
@@ -14,10 +16,11 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE;
 
 // [#protodoc-title: File Based Key Value Store storage plugin]
 
-// [#alpha:]
 // [#extension: envoy.key_value.file_based]
 // This is configuration to flush a key value store out to disk.
 message FileBasedKeyValueStoreConfig {
+  option (xds.annotations.v3.message_status).work_in_progress = true;
+
   // The filename to read the keys and values from, and write the keys and
   // values to.
   string filename = 1 [(validate.rules).string = {min_len: 1}];