Skip to content

Stable Envoy API versions #6271

@htuch

Description

@htuch

We've had feedback from folks (in particular gRPC-LB) that the current Breaking Change Policy is insufficient for handling long-term compatibility at the wire and generated proto level.

Specifically:

  1. Coupling API field validity and deprecation to Envoy release cycles is an implicit API state that mostly makes sense for Envoy but not for independent clients. Even Structured version and feature reporting #5405 introduces too much pain for non-Envoy clients.
  2. Upgrading to oneof and other wire compatible changes breaks Go code generation for protobuf. There are no safe mutations to existing proto fields.

The proposal here is that we switch to semantic versioning by making use of package namespaces. Any API that is not marked as alpha, e.g. v2alpha, becomes immutable modulo field addition. Deprecation would happen by moving to v3, v4, etc.

What do folks think? CC @envoyproxy/maintainers @alyssawilk

Metadata

Metadata

Assignees

Labels

area/xdsdesign proposalNeeds design doc/proposal before implementationno stalebotDisables stalebot from closing an issue

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions