Implement resource minor/patch version scheme in stable API versioning proposal

[htuch]

The basic idea is we maintain an annotation in the protos specifying minor version and some semantic hash of the proto contents. A bump of the minor version is forced when the hash changes by presubmit tooling. The minor version will be provided in DiscoveryRequests (while the major version is a part of the package/type name itself). See https://docs.google.com/document/d/1xeVvJ6KjFBkNjVspPbY_PwEDHC7XPi0J5p1SqUXcCl8/edit#heading=h.jlxlwbbptdag and https://docs.google.com/document/d/1xeVvJ6KjFBkNjVspPbY_PwEDHC7XPi0J5p1SqUXcCl8/edit#heading=h.9i8j2wwt08lg for further details.

This issue tracks finalizing the design and implementation and updating API_VERSIONING.md to reflect.

[markdroth]

Here's my off-the-cuff thought here, just to get discussion going:

It's not entirely clear to me that it makes sense to bump the minor version whenever the protos change. WIth that approach, the minor version number will be constantly incrementing to the point where it will basically be meaningless, because no one will remember which feature corresponds to which version. I think client features are a lot easier to reason about and understand, and they can be applied only when needed (typically when a newer field replaces an older one, as opposed to adding something completely new).

[mattklein123]

@markdroth I'm going to do a straw proposal in a doc and will send it around next week for discussion. Agree on your general sentiment above.

[markdroth]

@mattklein123 Sounds good -- I'll look forward to seeing it.

[mattklein123]

Short straw proposal here: https://docs.google.com/document/d/1afQ9wthJxofwOMCAle8qF-ckEfNWUuWtxbmdhxji0sI/edit# cc @envoyproxy/api-shepherds @alyssawilk

[mattklein123]

Doc has been heavily edited based on initial comments. I think it's ready now for wider review. PTAL.

[mattklein123]

Hi all,

The doc has been edited again to a hopefully near final statement. The salient points here are:

1. Yearly minor version API release alongside the Q1 Envoy release.
2. 1 year deprecation window for fields (this means that a deprecated field will be implemented in the code base for 1 - 2 years depending on deprecation time).
3. Fatal by default is not part of this proposal. Envoy will still implement it on a 6 month clock as it does today. It will be possible to completely disable this functionality via CLI/runtime flag (not just for individual deprecations) which may be desirable for some CPaaS deployments.

Thank you!

[mattklein123]

I haven't received any further comments on this proposal so I think we can consider this approved. I will be working with @htuch to figure out when this will be implemented (likely Q4).

[htuch]

Assigning to @adisuissa who is working on this.