diff --git a/STYLE.md b/STYLE.md index ffd595b5..48bab57b 100644 --- a/STYLE.md +++ b/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 = "";` 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. diff --git a/bazel/repository_locations.bzl b/bazel/repository_locations.bzl index 58006dae..50390b2a 100644 --- a/bazel/repository_locations.bzl +++ b/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" diff --git a/envoy/config/filter/http/cache/v2alpha/cache.proto b/envoy/config/filter/http/cache/v2alpha/cache.proto index 6d1cf5d2..4005b32a 100644 --- a/envoy/config/filter/http/cache/v2alpha/cache.proto +++ b/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] diff --git a/envoy/config/transport_socket/tap/v2alpha/tap.proto b/envoy/config/transport_socket/tap/v2alpha/tap.proto index e25449a0..53add0a9 100644 --- a/envoy/config/transport_socket/tap/v2alpha/tap.proto +++ b/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] diff --git a/envoy/extensions/filters/http/cache/v3alpha/cache.proto b/envoy/extensions/filters/http/cache/v3alpha/cache.proto index ad74fe7e..26016442 100644 --- a/envoy/extensions/filters/http/cache/v3alpha/cache.proto +++ b/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]