api: remove stale annotations. (envoyproxy#8468)

* [#not-implemented-warn:] was barely used and its purposes are better served by [#not-implemented-hide:]. * [#proto-status:] was there for an earlier style of versioning, where APIs were "frozen" or "draft", etc. Now we have semantic versioning and a regular API clock as per envoyproxy#6271. Part of envoyproxy#8371. Risk level: Low (docs only). Testing: Docs rebuild. Signed-off-by: Harvey Tuch <[email protected]>
nandu-vinodan · Oct 17, 2019 · 9595a4c · 9595a4c
1 parent 2a5d583
commit 9595a4c
Show file tree

Hide file tree

Showing 22 changed files with 5 additions and 53 deletions.
diff --git a/api/envoy/api/v2/auth/cert.proto b/api/envoy/api/v2/auth/cert.proto
@@ -382,7 +382,6 @@ message DownstreamTlsContext {
   }
 }
 
-// [#proto-status: experimental]
 message SdsSecretConfig {
   // Name (FQDN, UUID, SPKI, SHA256, etc.) by which the secret can be uniquely referred to.
   // When both name and config are specified, then secret can be fetched and/or reloaded via SDS.
@@ -393,7 +392,6 @@ message SdsSecretConfig {
   core.ConfigSource sds_config = 2;
 }
 
-// [#proto-status: experimental]
 message Secret {
   // Name (FQDN, UUID, SPKI, SHA256, etc.) by which the secret can be uniquely referred to.
   string name = 1;

diff --git a/api/envoy/api/v2/cds.proto b/api/envoy/api/v2/cds.proto
@@ -799,8 +799,6 @@ message Cluster {
 //
 // To facilitate this, the config message for the top-level LB policy may include a field of
 // type LoadBalancingPolicy that specifies the child policy.
-//
-// [#proto-status: experimental]
 message LoadBalancingPolicy {
   message Policy {
     // Required. The name of the LB policy.

diff --git a/api/envoy/api/v2/core/grpc_service.proto b/api/envoy/api/v2/core/grpc_service.proto
@@ -27,7 +27,6 @@ message GrpcService {
     string cluster_name = 1 [(validate.rules).string = {min_bytes: 1}];
   }
 
-  // [#proto-status: draft]
   message GoogleGrpc {
     // See https://grpc.io/grpc/cpp/structgrpc_1_1_ssl_credentials_options.html.
     message SslCredentials {

diff --git a/api/envoy/api/v2/srds.proto b/api/envoy/api/v2/srds.proto
@@ -23,7 +23,6 @@ import "validate/validate.proto";
 // dynamically assign a routing table (specified via a
 // :ref:`RouteConfiguration<envoy_api_msg_RouteConfiguration>` message) to each
 // HTTP request.
-// [#proto-status: experimental]
 service ScopedRoutesDiscoveryService {
   rpc StreamScopedRoutes(stream DiscoveryRequest) returns (stream DiscoveryResponse) {
   }
@@ -99,7 +98,6 @@ service ScopedRoutesDiscoveryService {
 // RouteConfiguration being assigned to the HTTP request/stream.
 //
 // [#comment:next free field: 4]
-// [#proto-status: experimental]
 message ScopedRouteConfiguration {
   // Specifies a key which is matched against the output of the
   // :ref:`scope_key_builder<envoy_api_field_config.filter.network.http_connection_manager.v2.ScopedRoutes.scope_key_builder>`

diff --git a/api/envoy/api/v3alpha/auth/cert.proto b/api/envoy/api/v3alpha/auth/cert.proto
@@ -382,7 +382,6 @@ message DownstreamTlsContext {
   }
 }
 
-// [#proto-status: experimental]
 message SdsSecretConfig {
   // Name (FQDN, UUID, SPKI, SHA256, etc.) by which the secret can be uniquely referred to.
   // When both name and config are specified, then secret can be fetched and/or reloaded via SDS.
@@ -393,7 +392,6 @@ message SdsSecretConfig {
   core.ConfigSource sds_config = 2;
 }
 
-// [#proto-status: experimental]
 message Secret {
   // Name (FQDN, UUID, SPKI, SHA256, etc.) by which the secret can be uniquely referred to.
   string name = 1;

diff --git a/api/envoy/api/v3alpha/cds.proto b/api/envoy/api/v3alpha/cds.proto
@@ -793,8 +793,6 @@ message Cluster {
 //
 // To facilitate this, the config message for the top-level LB policy may include a field of
 // type LoadBalancingPolicy that specifies the child policy.
-//
-// [#proto-status: experimental]
 message LoadBalancingPolicy {
   message Policy {
     // Required. The name of the LB policy.

diff --git a/api/envoy/api/v3alpha/core/grpc_service.proto b/api/envoy/api/v3alpha/core/grpc_service.proto
@@ -27,7 +27,6 @@ message GrpcService {
     string cluster_name = 1 [(validate.rules).string = {min_bytes: 1}];
   }
 
-  // [#proto-status: draft]
   message GoogleGrpc {
     // See https://grpc.io/grpc/cpp/structgrpc_1_1_ssl_credentials_options.html.
     message SslCredentials {

diff --git a/api/envoy/api/v3alpha/srds.proto b/api/envoy/api/v3alpha/srds.proto
@@ -23,7 +23,6 @@ import "validate/validate.proto";
 // dynamically assign a routing table (specified via a
 // :ref:`RouteConfiguration<envoy_api_msg_RouteConfiguration>` message) to each
 // HTTP request.
-// [#proto-status: experimental]
 service ScopedRoutesDiscoveryService {
   rpc StreamScopedRoutes(stream DiscoveryRequest) returns (stream DiscoveryResponse) {
   }
@@ -99,7 +98,6 @@ service ScopedRoutesDiscoveryService {
 // RouteConfiguration being assigned to the HTTP request/stream.
 //
 // [#comment:next free field: 4]
-// [#proto-status: experimental]
 message ScopedRouteConfiguration {
   // Specifies a key which is matched against the output of the
   // :ref:`scope_key_builder<envoy_api_field_config.filter.network.http_connection_manager.v3alpha.ScopedRoutes.scope_key_builder>`

diff --git a/api/envoy/config/filter/http/original_src/v2alpha1/original_src.proto b/api/envoy/config/filter/http/original_src/v2alpha1/original_src.proto
@@ -18,6 +18,5 @@ message OriginalSrc {
   // Sets the SO_MARK option on the upstream connection's socket to the provided value. Used to
   // ensure that non-local addresses may be routed back through envoy when binding to the original
   // source address. The option will not be applied if the mark is 0.
-  // [#proto-status: experimental]
   uint32 mark = 1;
 }
diff --git a/api/envoy/config/filter/http/original_src/v3alpha/original_src.proto b/api/envoy/config/filter/http/original_src/v3alpha/original_src.proto
@@ -18,6 +18,5 @@ message OriginalSrc {
   // Sets the SO_MARK option on the upstream connection's socket to the provided value. Used to
   // ensure that non-local addresses may be routed back through envoy when binding to the original
   // source address. The option will not be applied if the mark is 0.
-  // [#proto-status: experimental]
   uint32 mark = 1;
 }
diff --git a/api/envoy/config/filter/http/squash/v2/squash.proto b/api/envoy/config/filter/http/squash/v2/squash.proto
@@ -14,7 +14,6 @@ import "validate/validate.proto";
 // [#protodoc-title: Squash]
 // Squash :ref:`configuration overview <config_http_filters_squash>`.
 
-// [#proto-status: experimental]
 message Squash {
   // The name of the cluster that hosts the Squash server.
   string cluster = 1 [(validate.rules).string = {min_bytes: 1}];

diff --git a/api/envoy/config/filter/http/squash/v3alpha/squash.proto b/api/envoy/config/filter/http/squash/v3alpha/squash.proto
@@ -14,7 +14,6 @@ import "validate/validate.proto";
 // [#protodoc-title: Squash]
 // Squash :ref:`configuration overview <config_http_filters_squash>`.
 
-// [#proto-status: experimental]
 message Squash {
   // The name of the cluster that hosts the Squash server.
   string cluster = 1 [(validate.rules).string = {min_bytes: 1}];

diff --git a/api/envoy/config/filter/listener/original_src/v2alpha1/original_src.proto b/api/envoy/config/filter/listener/original_src/v2alpha1/original_src.proto
@@ -16,12 +16,11 @@ import "validate/validate.proto";
 // could come from trusted http headers.
 message OriginalSrc {
   // Whether to bind the port to the one used in the original downstream connection.
-  // [#not-implemented-warn:]
+  // [#not-implemented-hide:]
   bool bind_port = 1;
 
   // Sets the SO_MARK option on the upstream connection's socket to the provided value. Used to
   // ensure that non-local addresses may be routed back through envoy when binding to the original
   // source address. The option will not be applied if the mark is 0.
-  // [#proto-status: experimental]
   uint32 mark = 2;
 }
diff --git a/api/envoy/config/filter/listener/original_src/v3alpha/original_src.proto b/api/envoy/config/filter/listener/original_src/v3alpha/original_src.proto
@@ -16,12 +16,11 @@ import "validate/validate.proto";
 // could come from trusted http headers.
 message OriginalSrc {
   // Whether to bind the port to the one used in the original downstream connection.
-  // [#not-implemented-warn:]
+  // [#not-implemented-hide:]
   bool bind_port = 1;
 
   // Sets the SO_MARK option on the upstream connection's socket to the provided value. Used to
   // ensure that non-local addresses may be routed back through envoy when binding to the original
   // source address. The option will not be applied if the mark is 0.
-  // [#proto-status: experimental]
   uint32 mark = 2;
 }
diff --git a/api/envoy/config/trace/v2/trace.proto b/api/envoy/config/trace/v2/trace.proto
@@ -134,7 +134,6 @@ message DatadogConfig {
 }
 
 // Configuration for the OpenCensus tracer.
-// [#proto-status: experimental]
 message OpenCensusConfig {
   enum TraceContext {
     // No-op default, no trace context is utilized.

diff --git a/api/envoy/config/trace/v3alpha/trace.proto b/api/envoy/config/trace/v3alpha/trace.proto
@@ -134,7 +134,6 @@ message DatadogConfig {
 }
 
 // Configuration for the OpenCensus tracer.
-// [#proto-status: experimental]
 message OpenCensusConfig {
   enum TraceContext {
     // No-op default, no trace context is utilized.

diff --git a/api/envoy/service/discovery/v2/hds.proto b/api/envoy/service/discovery/v2/hds.proto
@@ -15,7 +15,6 @@ import "envoy/api/v2/endpoint/endpoint.proto";
 import "google/api/annotations.proto";
 import "google/protobuf/duration.proto";
 
-// [#proto-status: experimental]
 // HDS is Health Discovery Service. It compliments Envoy’s health checking
 // service by designating this Envoy to be a healthchecker for a subset of hosts
 // in the cluster. The status of these health checks will be reported to the

diff --git a/api/envoy/service/discovery/v3alpha/hds.proto b/api/envoy/service/discovery/v3alpha/hds.proto
@@ -15,7 +15,6 @@ import "envoy/api/v3alpha/endpoint/endpoint.proto";
 import "google/api/annotations.proto";
 import "google/protobuf/duration.proto";
 
-// [#proto-status: experimental]
 // HDS is Health Discovery Service. It compliments Envoy’s health checking
 // service by designating this Envoy to be a healthchecker for a subset of hosts
 // in the cluster. The status of these health checks will be reported to the

diff --git a/api/envoy/service/trace/v2/trace_service.proto b/api/envoy/service/trace/v2/trace_service.proto
@@ -1,7 +1,5 @@
 syntax = "proto3";
 
-// [#proto-status: draft]
-
 package envoy.service.trace.v2;
 
 option java_outer_classname = "TraceServiceProto";

diff --git a/api/envoy/service/trace/v3alpha/trace_service.proto b/api/envoy/service/trace/v3alpha/trace_service.proto
@@ -1,7 +1,5 @@
 syntax = "proto3";
 
-// [#proto-status: draft]
-
 package envoy.service.trace.v3alpha;
 
 option java_outer_classname = "TraceServiceProto";

diff --git a/tools/api_proto_plugin/annotations.py b/tools/api_proto_plugin/annotations.py
@@ -10,10 +10,6 @@
 # Page/section titles with special prefixes in the proto comments
 DOC_TITLE_ANNOTATION = 'protodoc-title'
 
-# Not implemented yet annotation on leading comments, leading to insertion of
-# warning on field.
-NOT_IMPLEMENTED_WARN_ANNOTATION = 'not-implemented-warn'
-
 # Not implemented yet annotation on leading comments, leading to hiding of
 # field.
 NOT_IMPLEMENTED_HIDE_ANNOTATION = 'not-implemented-hide'
@@ -25,21 +21,17 @@
 # Comment. Just used for adding text that will not go into the docs at all.
 COMMENT_ANNOTATION = 'comment'
 
-# proto compatibility status.
-PROTO_STATUS_ANNOTATION = 'proto-status'
-
 VALID_ANNOTATIONS = set([
     DOC_TITLE_ANNOTATION,
-    NOT_IMPLEMENTED_WARN_ANNOTATION,
     NOT_IMPLEMENTED_HIDE_ANNOTATION,
     NEXT_MAJOR_VERSION_ANNOTATION,
     COMMENT_ANNOTATION,
-    PROTO_STATUS_ANNOTATION,
 ])
 
 # These can propagate from file scope to message/enum scope (and be overridden).
 INHERITED_ANNOTATIONS = set([
-    PROTO_STATUS_ANNOTATION,
+    # Nothing here right now, this used to be PROTO_STATUS_ANNOTATION. Retaining
+    # this capability for potential future use.
 ])
 
 

diff --git a/tools/protodoc/protodoc.py b/tools/protodoc/protodoc.py
@@ -69,19 +69,7 @@ def FormatCommentWithAnnotations(comment, type_name=''):
   Returns:
     A string with additional RST from annotations.
   """
-  s = annotations.WithoutAnnotations(StripLeadingSpace(comment.raw) + '\n')
-  if annotations.NOT_IMPLEMENTED_WARN_ANNOTATION in comment.annotations:
-    s += '\n.. WARNING::\n  Not implemented yet\n'
-  if type_name == 'message' or type_name == 'enum':
-    if annotations.PROTO_STATUS_ANNOTATION in comment.annotations:
-      status = comment.annotations[annotations.PROTO_STATUS_ANNOTATION]
-      if status not in ['frozen', 'draft', 'experimental']:
-        raise ProtodocError('Unknown proto status: %s' % status)
-      if status == 'draft' or status == 'experimental':
-        s += (
-            '\n.. WARNING::\n This %s type has %s status and is subject to potential future breaking changes.\n'
-            % (type_name, status))
-  return s
+  return annotations.WithoutAnnotations(StripLeadingSpace(comment.raw) + '\n')
 
 
 def MapLines(f, s):