From 2e057f33f0cb196b3e697a5d9c1c0618ae7b7128 Mon Sep 17 00:00:00 2001 From: Alyssa Wilk Date: Thu, 2 Sep 2021 12:52:04 -0400 Subject: [PATCH 1/6] api docs update Signed-off-by: Alyssa Wilk --- api/STYLE.md | 27 ++++++++++++++++----------- 1 file changed, 16 insertions(+), 11 deletions(-) diff --git a/api/STYLE.md b/api/STYLE.md index d73e17b773b24..7748e8af3b0b4 100644 --- a/api/STYLE.md +++ b/api/STYLE.md @@ -112,10 +112,8 @@ Extensions must currently be added as v3 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/extensions/filters/http/cache/v3alpha/cache.proto) - as an example of `v3alpha`, and the - [Buffer filter config](envoy/extensions/filters/http/buffer/v3/buffer.proto) as an example of `v3`. +1. If this is still WiP and subject to breaking changes, please tag it as alpha (`[#alpha:]`), and + optionally hide it from the docs (`[#not-implemented-hide:]`. 1. Place the v3 extension configuration `.proto` in `api/envoy/extensions`, e.g. `api/envoy/extensions/filters/http/foobar/v3/foobar.proto` together with an initial BUILD file: ```bazel @@ -127,16 +125,23 @@ To add an extension config to the API, the steps below should be followed: deps = ["@com_github_cncf_udpa//udpa/annotations:pkg"], ) ``` -1. Add to the v3 extension config proto `import "udpa/annotations/status.proto";` -1. If this is still WiP and subject to breaking changes, set - `option (udpa.annotations.file_status).work_in_progress = true;`. -1. Add to the v3 extension config proto a file level - `option (udpa.annotations.file_status).package_version_status = ACTIVE;`. +1. Update `source/extensions/extensions_metadata.yaml` with the category, + security posture, and status. The category field will have to match an + annotation of the form `// [#extension-category: your.extension.category]` + one of the proto files for the docs build to pass. +1. If the extension is not hidden, find or create a docs file with a toctree + and to reference your proto to make sure users can navigate to it from the API docs + (and to not break the docs build). + See the [key-value-store PR](https://github.com/envoyproxy/envoy/pull/17745/files) for an example of adding a new extension point to common. +1. Make sure your proto imports the v3 extension config proto (`import "udpa/annotations/status.proto";`) +1. Make sure your proto is either tracked as a work in progress + (`option (udpa.annotations.file_status).work_in_progress = true;`) + or ready to be used + (`option (udpa.annotations.file_status).package_version_status = ACTIVE;`). This is required to automatically include the config proto in [api/versioning/BUILD](versioning/BUILD). 1. Add a reference to the v3 extension config in (1) in [api/versioning/BUILD](versioning/BUILD) under `active_protos`. 1. Run `./tools/proto_format/proto_format.sh fix`. This should regenerate the `BUILD` file, - reformat `foobar.proto` as needed and also generate the v4alpha extension config (if needed), - together with shadow API protos. + reformat `foobar.proto` as needed and also generate the shadow API protos. 1. `git add api/ generated_api_shadow/` to add any new files to your Git index. ## API annotations From b48d72e2d9a500b7e902f05e09e616a74de333aa Mon Sep 17 00:00:00 2001 From: Alyssa Wilk Date: Thu, 2 Sep 2021 12:54:54 -0400 Subject: [PATCH 2/6] repo link Signed-off-by: Alyssa Wilk --- api/STYLE.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api/STYLE.md b/api/STYLE.md index 7748e8af3b0b4..efbf167fb487d 100644 --- a/api/STYLE.md +++ b/api/STYLE.md @@ -125,8 +125,8 @@ To add an extension config to the API, the steps below should be followed: deps = ["@com_github_cncf_udpa//udpa/annotations:pkg"], ) ``` -1. Update `source/extensions/extensions_metadata.yaml` with the category, - security posture, and status. The category field will have to match an +1. Update [source/extensions/extensions_metadata.yaml](../source/extensions/extensions_metadata.yaml) + with the category, security posture, and status. The category field will have to match an annotation of the form `// [#extension-category: your.extension.category]` one of the proto files for the docs build to pass. 1. If the extension is not hidden, find or create a docs file with a toctree From fe0988fa76ca86e153ae46a1e15fd10632bcf444 Mon Sep 17 00:00:00 2001 From: Alyssa Wilk Date: Thu, 2 Sep 2021 12:56:57 -0400 Subject: [PATCH 3/6] missing word Signed-off-by: Alyssa Wilk --- api/STYLE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/STYLE.md b/api/STYLE.md index efbf167fb487d..a10d93657b586 100644 --- a/api/STYLE.md +++ b/api/STYLE.md @@ -128,7 +128,7 @@ To add an extension config to the API, the steps below should be followed: 1. Update [source/extensions/extensions_metadata.yaml](../source/extensions/extensions_metadata.yaml) with the category, security posture, and status. The category field will have to match an annotation of the form `// [#extension-category: your.extension.category]` - one of the proto files for the docs build to pass. + in one of the proto files for the docs build to pass. 1. If the extension is not hidden, find or create a docs file with a toctree and to reference your proto to make sure users can navigate to it from the API docs (and to not break the docs build). From e4ae34628f0762f64ef26087bafc0d28c949742d Mon Sep 17 00:00:00 2001 From: Alyssa Wilk Date: Thu, 2 Sep 2021 13:44:03 -0400 Subject: [PATCH 4/6] dedup Signed-off-by: Alyssa Wilk --- CONTRIBUTING.md | 10 ++-------- api/STYLE.md | 3 +++ 2 files changed, 5 insertions(+), 8 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c59d73c0e7222..a42b65cf0e333 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -253,15 +253,9 @@ Extension configuration should be located in a directory structure like The code for the extension should be located under the equivalent `source/extensions/area/plugin`, and include an *envoy_cc_extension* with the configuration and tagged with the appropriate security posture, and an -*envoy_cc_library* with the code. More details on how to add a new extension -API can be found [here](api/STYLE.md#adding-an-extension-configuration-to-the-api): +*envoy_cc_library* with the code. -Other changes will likely include - - * Editing [source/extensions/extensions_build_config.bzl](source/extensions/extensions_build_config.bzl) to include the new extensions - * Editing [source/extensions/extensions_metadata.yaml](source/extensions/extensions_metadata.yaml) to include metadata for the new extensions - * Editing [docs/root/api-v3/config/config.rst](docs/root/api-v3/config/config.rst) to add area/area - * Adding `docs/root/api-v3/config/area/area.rst` to add a table of contents for the API docs +More details on how to add a new extension API can be found [here](api/STYLE.md#adding-an-extension-configuration-to-the-api): # Adding contrib extensions diff --git a/api/STYLE.md b/api/STYLE.md index a10d93657b586..7341e0682e7ec 100644 --- a/api/STYLE.md +++ b/api/STYLE.md @@ -129,6 +129,9 @@ To add an extension config to the API, the steps below should be followed: with the category, security posture, and status. The category field will have to match an annotation of the form `// [#extension-category: your.extension.category]` in one of the proto files for the docs build to pass. +1. Update + [source/extensions/extensions_build_config.bzl](source/extensions/extensions_build_config.bzl) + to include the new extension. 1. If the extension is not hidden, find or create a docs file with a toctree and to reference your proto to make sure users can navigate to it from the API docs (and to not break the docs build). From 05eaca405bc97c1b32b49d1e34211c5cf281080a Mon Sep 17 00:00:00 2001 From: Alyssa Wilk Date: Wed, 8 Sep 2021 08:41:12 -0400 Subject: [PATCH 5/6] format Signed-off-by: Alyssa Wilk --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a42b65cf0e333..9b6e47913f07f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -253,7 +253,7 @@ Extension configuration should be located in a directory structure like The code for the extension should be located under the equivalent `source/extensions/area/plugin`, and include an *envoy_cc_extension* with the configuration and tagged with the appropriate security posture, and an -*envoy_cc_library* with the code. +*envoy_cc_library* with the code. More details on how to add a new extension API can be found [here](api/STYLE.md#adding-an-extension-configuration-to-the-api): From 77aa345c6984daca8f794ad0caf7bcd44a48645a Mon Sep 17 00:00:00 2001 From: Alyssa Wilk Date: Wed, 8 Sep 2021 08:48:34 -0400 Subject: [PATCH 6/6] updating per #17920 Signed-off-by: Alyssa Wilk --- api/STYLE.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/api/STYLE.md b/api/STYLE.md index 7341e0682e7ec..b185be97c9687 100644 --- a/api/STYLE.md +++ b/api/STYLE.md @@ -112,7 +112,8 @@ Extensions must currently be added as v3 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, please tag it as alpha (`[#alpha:]`), and +1. If this is still WiP and subject to breaking changes, please tag it + `option (udpa.annotations.file_status).work_in_progress = true;` and optionally hide it from the docs (`[#not-implemented-hide:]`. 1. Place the v3 extension configuration `.proto` in `api/envoy/extensions`, e.g. `api/envoy/extensions/filters/http/foobar/v3/foobar.proto` together with an initial BUILD file: