api: new major versioning cut policy. #10958
Conversation
After extended discussion in envoyproxy#10852, Slack and offline, this patch proposes a revision to the API major versioning policy where we will: * Not mechanically cut a new major version at EOY, instead wait for enough tech debt. * Encourage the use of client feature capabilities as an alternative to manage client feature support. Fixes envoyproxy#10852. Signed-off-by: Harvey Tuch <htuch@google.com>
|
CC @markdroth @louiscryan @dfawley @ejona86 @envoyproxy/api-shepherds @alyssawilk |
|
We will review this at the community call tomorrow as well (draft until then). |
| than the API owners. There will be no major `vN` initiative to address technical debt beyond that | ||
| enabled by the above process. | ||
|
|
||
| # Client features |
There was a problem hiding this comment.
I'm not sure if it's worth tracking in this PR, but I do want to discuss enhancing the deprecated annotation so it might look more like this (in pseudo proto):
Foo foo = 1 [deprecated.in = {"envoy.1.16", "grpc.x.y", ...}
This would allow fields to be fully deprecated in particular versions, and in conjunction with client capabilities and early failure during config parsing, allow clients to actually clean up tech debt without bumping the major version API.
This needs a ton of thinking but it could make the need to upgrade major versions to perform tech debt cleanup much less frequent.
There was a problem hiding this comment.
I'm concerned this will lead to control planes having to do to much work and force intermediate caching layers to have to reason about version ranges, but we can discuss. There's a middle ground, e.g. adding an annotation to indicate the client feature capability needed to ask for this deprecated feature.
There was a problem hiding this comment.
To follow up on the community call conversation, I think there is some consensus on some combination of API point releases as well as client feature flags. I think we still want to encode most of this information inside a more sophisticated deprecated annotation. Let's work offline on a proposal, but I don't think it needs to block this PR. Not sure though if you want to do any edits based on our discussion and desired future direction though? cc @alyssawilk
There was a problem hiding this comment.
I've updated to:
- Refrain from committing to client feature capabilities for deprecations, while still leaving them there for cross-client support.
- Mention that minor versions are WiP and may introduce sunsetting of support inside a major version (after at least 1 year of support).
Does this sound reasonable? If so, we can merge this PR and then continue the discussion to hash this out some more. Your deprecated annotations probably will be part of the minor version scheme.
Signed-off-by: Harvey Tuch <htuch@google.com>
After extended discussion in #10852, Slack and offline, this patch proposes a revision to the API
major versioning policy where we will:
Not mechanically cut a new major version at EOY, instead wait for enough tech debt.
Encourage the use of client feature capabilities as an alternative to manage client
feature support.
Fixes #10852.
Signed-off-by: Harvey Tuch htuch@google.com