From 4573a23d15c2f1767199dc3ecfe6501613289077 Mon Sep 17 00:00:00 2001 From: "data-plane-api(Azure Pipelines)" Date: Mon, 27 Sep 2021 19:03:50 +0000 Subject: [PATCH] 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 Mirrored from https://github.com/envoyproxy/envoy @ f0f17a3caa75106a9e28b99edc27dd09c1bed488 --- API_VERSIONING.md | 6 ++++-- STYLE.md | 11 +++++++---- bazel/repository_locations.bzl | 6 +++--- .../filters/network/kafka_mesh/v3alpha/BUILD | 5 ++++- .../network/kafka_mesh/v3alpha/kafka_mesh.proto | 4 +++- envoy/config/common/key_value/v3/BUILD | 1 + envoy/config/common/key_value/v3/config.proto | 5 ++++- envoy/config/common/matcher/v3/BUILD | 1 + envoy/config/common/matcher/v3/matcher.proto | 6 ++++-- envoy/config/core/v3/BUILD | 1 + envoy/config/core/v3/protocol.proto | 6 ++++-- envoy/extensions/common/matching/v3/BUILD | 1 + .../common/matching/v3/extension_matcher.proto | 5 +++-- envoy/extensions/filters/http/composite/v3/BUILD | 1 + .../filters/http/composite/v3/composite.proto | 5 +++-- envoy/extensions/key_value/file_based/v3/BUILD | 5 ++++- envoy/extensions/key_value/file_based/v3/config.proto | 5 ++++- 17 files changed, 52 insertions(+), 22 deletions(-) diff --git a/API_VERSIONING.md b/API_VERSIONING.md index f8646196..49e1bae1 100644 --- a/API_VERSIONING.md +++ b/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 diff --git a/STYLE.md b/STYLE.md index 485ab575..5689d116 100644 --- a/STYLE.md +++ b/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`. diff --git a/bazel/repository_locations.bzl b/bazel/repository_locations.bzl index be1e9c97..ac80f72a 100644 --- a/bazel/repository_locations.bzl +++ b/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"], diff --git a/contrib/envoy/extensions/filters/network/kafka_mesh/v3alpha/BUILD b/contrib/envoy/extensions/filters/network/kafka_mesh/v3alpha/BUILD index ee92fb65..ec1e778e 100644 --- a/contrib/envoy/extensions/filters/network/kafka_mesh/v3alpha/BUILD +++ b/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", + ], ) diff --git a/contrib/envoy/extensions/filters/network/kafka_mesh/v3alpha/kafka_mesh.proto b/contrib/envoy/extensions/filters/network/kafka_mesh/v3alpha/kafka_mesh.proto index 03a65228..88fd46c3 100644 --- a/contrib/envoy/extensions/filters/network/kafka_mesh/v3alpha/kafka_mesh.proto +++ b/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 `. diff --git a/envoy/config/common/key_value/v3/BUILD b/envoy/config/common/key_value/v3/BUILD index 1c1a6f6b..e9b556d6 100644 --- a/envoy/config/common/key_value/v3/BUILD +++ b/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", ], ) diff --git a/envoy/config/common/key_value/v3/config.proto b/envoy/config/common/key_value/v3/config.proto index 39bf79fe..8d62c098 100644 --- a/envoy/config/common/key_value/v3/config.proto +++ b/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}]; } diff --git a/envoy/config/common/matcher/v3/BUILD b/envoy/config/common/matcher/v3/BUILD index 2f90ace8..221350b7 100644 --- a/envoy/config/common/matcher/v3/BUILD +++ b/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", ], ) diff --git a/envoy/config/common/matcher/v3/matcher.proto b/envoy/config/common/matcher/v3/matcher.proto index d7deb71d..1fb8c83e 100644 --- a/envoy/config/common/matcher/v3/matcher.proto +++ b/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 { diff --git a/envoy/config/core/v3/BUILD b/envoy/config/core/v3/BUILD index 72e10b6d..3fbb6b0e 100644 --- a/envoy/config/core/v3/BUILD +++ b/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", ], ) diff --git a/envoy/config/core/v3/protocol.proto b/envoy/config/core/v3/protocol.proto index f65f8937..4535b166 100644 --- a/envoy/config/core/v3/protocol.proto +++ b/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 { // `_ // and settings `proposed for HTTP/3 // `_ - // [#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 diff --git a/envoy/extensions/common/matching/v3/BUILD b/envoy/extensions/common/matching/v3/BUILD index 1afd4545..de9e1202 100644 --- a/envoy/extensions/common/matching/v3/BUILD +++ b/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", ], ) diff --git a/envoy/extensions/common/matching/v3/extension_matcher.proto b/envoy/extensions/common/matching/v3/extension_matcher.proto index eee82a38..10bd3b73 100644 --- a/envoy/extensions/common/matching/v3/extension_matcher.proto +++ b/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"]; diff --git a/envoy/extensions/filters/http/composite/v3/BUILD b/envoy/extensions/filters/http/composite/v3/BUILD index 1c1a6f6b..e9b556d6 100644 --- a/envoy/extensions/filters/http/composite/v3/BUILD +++ b/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", ], ) diff --git a/envoy/extensions/filters/http/composite/v3/composite.proto b/envoy/extensions/filters/http/composite/v3/composite.proto index f8a3bd83..a53364e8 100644 --- a/envoy/extensions/filters/http/composite/v3/composite.proto +++ b/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 `) // 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 ` for more info on match actions). diff --git a/envoy/extensions/key_value/file_based/v3/BUILD b/envoy/extensions/key_value/file_based/v3/BUILD index ee92fb65..ec1e778e 100644 --- a/envoy/extensions/key_value/file_based/v3/BUILD +++ b/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", + ], ) diff --git a/envoy/extensions/key_value/file_based/v3/config.proto b/envoy/extensions/key_value/file_based/v3/config.proto index 0eff4feb..82aa94f8 100644 --- a/envoy/extensions/key_value/file_based/v3/config.proto +++ b/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}];