Reduce ambiguity in beta backwards compatibility policy

[bobcatfish]

In #2697 @dlorenc pointed out that our backwards compatibility policy (https://github.com/tektoncd/pipeline/blob/master/api_compatibility_policy.md) is a bit vague:

Removing the field from our API. The policy is a bit unclear - if we release a v1beta2 without this field, do we need to wait 9 months?

Our policy currently says:

You will be given at least 9 months to migrate before a backward incompatible change is made.

I understood this to mean that we would need to wait at least 9 months before creating a release that included this as a backwards incompatible change, e.g. introducing a deprecation notice in July 2020 would mean that there could be no release (even v1beta2) that included the change as backwards incompatible until Apr 2021

However we also are trying to follow the kubernetes policy (https://kubernetes.io/docs/reference/using-api/deprecation-policy/) which says:

Rule #4a: Other than the most recent API versions in each track, older API versions must be supported after their announced deprecation for a duration of no less than:
Beta: 9 months or 3 releases (whichever is longer)

This seems to imply that according to our policy, we could create v1beta2 tomorrow, including backwards incompatible changes, and that would be totally fine, as long as we continue to support v1beta1 for at least 9 months.

I want to check how other folks understand this and maybe update our docs to be a bit more clear.

[vdemeester]

In #2697 @dlorenc pointed out that our backwards compatibility policy (https://github.com/tektoncd/pipeline/blob/master/api_compatibility_policy.md) is a bit vague:

Removing the field from our API. The policy is a bit unclear - if we release a v1beta2 without this field, do we need to wait 9 months?

Our policy currently says:

You will be given at least 9 months to migrate before a backward incompatible change is made.

I understood this to mean that we would need to wait at least 9 months before creating a release that included this as a backwards incompatible change, e.g. introducing a deprecation notice in July 2020 would mean that there could be no release (even v1beta2) that included the change as backwards incompatible until Apr 2021

However we also are trying to follow the kubernetes policy (https://kubernetes.io/docs/reference/using-api/deprecation-policy/) which says:

Rule #4a: Other than the most recent API versions in each track, older API versions must be supported after their announced deprecation for a duration of no less than:
Beta: 9 months or 3 releases (whichever is longer)

This seems to imply that according to our policy, we could create v1beta2 tomorrow, including backwards incompatible changYou will be given at least 9 months to migrate before a backward incompatible change is made.es, and that would be totally fine, as long as we continue to support v1beta1 for at least 9 months.

I want to check how other folks understand this and maybe update our docs to be a bit more clear.

Yes, as you said, the "You will be given at least 9 months to migrate before a backward incompatible change is made." is on a given API version, so if you release a v1beta2 API version (a new version) you can have that field removed. But you need to support v1beta1 (and that field) for at least the 9 months 😉

If we need to make it more explicit on the doc, let's do it 😉

[bobcatfish]

If that's the case I think the table at https://github.com/tektoncd/pipeline/blob/master/docs/deprecations.md#deprecation-table is a bit misleading - the question isnt really about the earliest date the field could be removed (which had been my understanding before this discussion!) but it's about when we'd stop supporting v1beta1 period, which sounds like it would be at a minimum 9 months after releasing v1beta2.

I suggest then that we remove the dates column from that table and also that we start talking about when we want to look at v1beta2: we could pick a target now, or we could review the list of deprecations every couple months and decide.

[dlorenc]

So to clarify, here's my understanding:

The # of months applies to backwards incompatible changes. These can come in (at least) two flavors:

• API changes. A v1betaN release will be supported for at least 9 months from the time a v1betaN+1 comes out.
• Non API, behavioral changes. A Tekton feature will change in a backwards incompatible way, that cannot be gated by an API version. These should be flag-gated, and those flags should stick around for whatever time period the release level for that component dictates. (Alpha means just one release, Beta is 9 months, etc.).

Is this correct?

[vdemeester]

@dlorenc yes