api: document annotations and how to add an extension config. (#9672)

Fix #9550
Partly addresses #5263

Signed-off-by: Harvey Tuch <htuch@google.com>

Mirrored from https://github.com/envoyproxy/envoy @ ce4a4ad64a7d0b6c344726ec0e7a0f209796fb97

API_VERSIONING.md

@@ -76,7 +76,7 @@ implementations within a major version should set explicit values for these fiel
 
 # API lifecycle
 
-The API lifecycle follows a calendar clock. At the end of Q3 each year, a major API version
+The API lifecycle follows a calendar clock. At the end of Q4 each year, a major API version
 increment may occur for any Envoy API package, in concert with the quarterly Envoy release.
 
 Envoy will support at most three major versions of any API package at all times:
@@ -134,17 +134,9 @@ methods, depending on whether the change is mechanical or manual.
 
 ## Mechanical breaking changes
 
-Field deprecations, renames, etc. are mechanical changes that will be supported by the
+Field deprecations, renames, etc. are mechanical changes that are supported by the
 [protoxform](https://github.com/envoyproxy/envoy/tree/master/tools/protoxform) tool. These are
-guided by annotations in protobuf.
-* Deprecations are specified with the built-in protobuf deprecated option set on a message, enum,
-  field or enum value. No field may be marked as deprecated unless a replacement for this
-  functionality exists and the corresponding Envoy implementation is production ready.
-
-* Renames are specified with a `[(udpa.annotations.field_migrate).rename = "<new name>"]` annotation.
-
-* We anticipate that `protoxform` will also support `oneof` promotion, package movement, etc. via
-  similar annotations.
+guided by [annotations](STYLE.md#api-annotations).
 
 ## Manual breaking changes
 

STYLE.md

@@ -113,3 +113,67 @@ for services and configs should be `//docs` (proto documentation tool).
 
 Extensions should use the regular hierarchy. For example, configuration for network filters belongs
 in a package under `envoy.config.filter.network`.
+
+## Adding an extension configuration to the API
+
+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. Place the v2 extension configuration `.proto` in `api/config`, e.g.
+   `api/config/filter/http/foobar/v2/foobar.proto` together with an initial BUILD file:
+   ```
+   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"],
+       )
+   ```
+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.v3alpha";`.
+   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,
+   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.
+
+## API annotations
+
+A number of annotations are used in the Envoy APIs to provide additional API
+metadata. We describe these annotations below by category.
+
+### Field level
+* `[deprecated = true]` to denote fields that are deprecated in a major version.
+  These fields are slated for removal at the next major cycle and follow the
+  [breaking change policy](../CONTRIBUTING.md#breaking-change-policy).
+* `[envoy.annotations.disallowed_by_default = true]` to denote fields that have
+  been disallowed by default as per the [breaking change policy](../CONTRIBUTING.md#breaking-change-policy).
+* `[(udpa.annotations.field_migrate).rename = "<new field name>"]` to denote that
+  the field will be renamed to a given name in the next API major version.
+* `[(udpa.annotations.field_migrate).oneof_promotion = "<oneof name>"]` to denote that
+  the field will be promoted to a given `oneof` in the next API major version.
+* `[(udpa.annotations.sensitive) = true]` to denote sensitive fields that
+  should be redacted in output such as logging or configuration dumps.
+* [PGV annotations](https://github.com/envoyproxy/protoc-gen-validate) to denote field
+  value constraints.
+
+### Enum value level
+* `[(udpa.annotations.enum_value_migrate).rename = "new enum value name"]` to denote that
+  the enum value will be renamed to a given name in the next API major version.
+
+### Message level
+* `option (udpa.annotations.versioning).previous_message_type = "<message type
+  name>";` to denote the previous type name for an upgraded message. You should
+  never have to write these manually, they are generated by `protoxform`.
+
+### Service level
+* `option (envoy.annotations.resource).type = "<resource type name>";` to denote
+  the resource type for an xDS service definition.
+
+### File level
+* `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`.