api: introduce WiP file-level annotations. (#9971)

This is the new style for indicating a file is WiP and subject to
breaking changes. Rather than rely on alpha major versions, which are
coarse grained and introduce migration difficulties for operators, we
use a file-level annotation.

Risk level: Low
Testing: API/docs build, manual inspection of docs.

Fixes #9769.

Signed-off-by: Lizan Zhou <lizan@tetrate.io>
Co-authored-by: htuch <htuch@users.noreply.github.com>

Mirrored from https://github.com/envoyproxy/envoy @ 423fe76d5572bb4f1505391ccaaacf39b2bf2c85

STYLE.md

@@ -120,6 +120,10 @@ Extensions must currently be added as v2 APIs following the [package
 organization](#package-organization) above.
 To add an extension config to the API, the steps below should be followed:
 
+1. If this is still WiP and subject to breaking changes, use `vNalpha` instead of `vN` in steps
+   below. Refer to the [Cache filter config](envoy/config/filter/http/cache/v2alpha/cache.proto)
+   as an example of `v2alpha`, and the
+   [Buffer filter config](envoy/config/filter/http/buffer/v2/buffer.proto) as an example of `v2`.
 1. Place the v2 extension configuration `.proto` in `api/envoy/config`, e.g.
    `api/envoy/config/filter/http/foobar/v2/foobar.proto` together with an initial BUILD file:
    ```
@@ -132,13 +136,15 @@ To add an extension config to the API, the steps below should be followed:
        )
    ```
 1. Add to the v2 extension config proto `import "udpa/annotations/migrate.proto";`
-2. Add to the v2 extension config proto a package level `option (udpa.annotations.file_migrate).move_to_package = "envoy.extensions.filters.http.foobar.v3";`.
-   This places the filter in the correct [v3 package hierarchy](#package-organization).
-3. Add a reference to the v2 extension config in (1) in [api/docs/BUILD](docs/BUILD).
-4. Run `./tools/proto_format fix`. This should regenerate the `BUILD` file,
+1. Add to the v2 extension config proto a file level `option (udpa.annotations.file_migrate).move_to_package = "envoy.extensions.filters.http.foobar.v3";`.
+   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. Run `./tools/proto_format fix`. This should regenerate the `BUILD` file,
    reformat `foobar.proto` as needed and also generate the v3 extension config,
    together with shadow API protos.
-4. `git add api/ generated_api_shadow/` to add any new files to your Git index.
+1. `git add api/ generated_api_shadow/` to add any new files to your Git index.
 
 ## API annotations
 
@@ -177,3 +183,5 @@ metadata. We describe these annotations below by category.
 * `option (udpa.annotations.file_migrate).move_to_package = "<package name>";`
   to denote that in the next major version of the API, the file will be moved to
   the given package. This is consumed by `protoxform`.
+* `option (udpa.annotations.file_status).work_in_progress = true;` to denote a
+  file that is still work-in-progress and subject to breaking changes.

bazel/repository_locations.bzl

@@ -13,8 +13,8 @@ GOOGLEAPIS_SHA = "a45019af4d3290f02eaeb1ce10990166978c807cb33a9692141a076ba46d14
 PROMETHEUS_GIT_SHA = "99fa1f4be8e564e8a6b613da7fa6f46c9edafc6c"  # Nov 17, 2017
 PROMETHEUS_SHA = "783bdaf8ee0464b35ec0c8704871e1e72afa0005c3f3587f65d9d6694bf3911b"
 
-UDPA_GIT_SHA = "edbea6a78f6d1ba34edc69c53a396b1d88d59651"  # Dec 30, 2019
-UDPA_SHA256 = "8cabd617b68354fa8b4adab8a031f80c10e2ea43f57d5f6210bc7b3ebb79b684"
+UDPA_GIT_SHA = "db4b343e48c1264bb4d9ff491b059300701dc7c7"  # Jan 24, 2020
+UDPA_SHA256 = "800624f44592a24898f133e39ae7fbb7a6c4b85bdddd448185fb7e277f097a56"
 
 ZIPKINAPI_RELEASE = "0.2.2"  # Aug 23, 2019
 ZIPKINAPI_SHA256 = "688c4fe170821dd589f36ec45aaadc03a618a40283bc1f97da8fa11686fc816b"

envoy/config/filter/http/cache/v2alpha/cache.proto

@@ -7,6 +7,8 @@ import "envoy/type/matcher/string.proto";
 
 import "google/protobuf/any.proto";
 
+import "udpa/annotations/status.proto";
+
 import "udpa/annotations/migrate.proto";
 import "validate/validate.proto";
 
@@ -15,6 +17,7 @@ option java_outer_classname = "CacheProto";
 option java_multiple_files = true;
 option (udpa.annotations.file_migrate).move_to_package =
     "envoy.extensions.filters.http.cache.v3alpha";
+option (udpa.annotations.file_status).work_in_progress = true;
 
 // [#protodoc-title: HTTP Cache Filter]
 // [#extension: envoy.filters.http.cache]

envoy/config/transport_socket/tap/v2alpha/tap.proto

@@ -5,6 +5,8 @@ package envoy.config.transport_socket.tap.v2alpha;
 import "envoy/api/v2/core/base.proto";
 import "envoy/config/common/tap/v2alpha/common.proto";
 
+import "udpa/annotations/status.proto";
+
 import "udpa/annotations/migrate.proto";
 import "validate/validate.proto";
 
@@ -13,6 +15,7 @@ option java_outer_classname = "TapProto";
 option java_multiple_files = true;
 option (udpa.annotations.file_migrate).move_to_package =
     "envoy.extensions.transport_sockets.tap.v3";
+option (udpa.annotations.file_status).work_in_progress = true;
 
 // [#protodoc-title: Tap]
 // [#extension: envoy.transport_sockets.tap]

envoy/extensions/filters/http/cache/v3alpha/cache.proto

@@ -7,6 +7,7 @@ import "envoy/type/matcher/v3/string.proto";
 
 import "google/protobuf/any.proto";
 
+import "udpa/annotations/status.proto";
 import "udpa/annotations/versioning.proto";
 
 import "validate/validate.proto";
@@ -14,6 +15,7 @@ import "validate/validate.proto";
 option java_package = "io.envoyproxy.envoy.extensions.filters.http.cache.v3alpha";
 option java_outer_classname = "CacheProto";
 option java_multiple_files = true;
+option (udpa.annotations.file_status).work_in_progress = true;
 
 // [#protodoc-title: HTTP Cache Filter]
 // [#extension: envoy.filters.http.cache]