While trying to send a pull request for an extension I was baffled multiple times by poor error messages and surprising behaviors. The alterations here each derive from a confusing thing that mostly also didn't get any clear "someone understood it better" signs from the dev slack channel.
First surprise, if you use option (udpa.annotations.file_status).work_in_progress = true; like the doc suggested, proto_format.sh would remove it. Suggestion from the slack channel was to use xds.annotations.v3.file_status instead, which this updates STYLE.md to reflect. (related slack thread)
Added a link to security posture and status documentation, which was otherwise hard to make sense of without foreknowledge.
Adjusted the section that suggests using work_in_progress=true or package_version_status=ACTIVE - any combination of these (with either xds or udpa version of work_in_progress) that doesn't involve package_version_status=ACTIVE causes proto_format.sh to delete the file entirely. So the only viable options appear to be just package_version_status=ACTIVE, or that and xds work_in_progress=true which is already covered in an earlier bulletpoint.
Clarified that without ACTIVE, proto_format.sh will delete the file (which hopefully will make it more discoverable for developers experiencing that symptom).
Added a mention of api/BUILD's v3_protos section, without which proto_format.sh will automatically remove any imports of your new proto from other protos.
Added mention of [#extension:] tag, which is also necessary, and extra detail about where [#extension-category:] has to go (it doesn't appear to work if present at the top-level). (related slack thread)
Risk Level: None, documentation only.
Testing: Verified that the old documentation doesn't work for at least one developer, and the new documentation is better. :)
Docs Changes: That's all this is.
Release Notes: n/a
Platform Specific Features: n/a
Signed-off-by: Raven Black <ravenblack@dropbox.com>
Mirrored from https://github.com/envoyproxy/envoy @ 2014cbea0f67e9513137eb6b4be3cb92ba437244
This tree hosts the configuration and APIs that drive Envoy. The
APIs are also in some cases used by other proxy solutions that aim to interoperate with management
systems and configuration generators that are built against this standard. Thus, we consider these a
set of universal data plane APIs. See this
blog post for more information on the universal data plane concept.
data-plane-api(Azure Pipelines)
b5f7974c3e