RFC: Update Go compatibility policy #6768
Conversation
tekton-robot
added
the
release-note-none
tekton-robot
added
kind/misc
api_compatibility_policy.md
Outdated
| - If support for an alpha field is dropped, the field will be tombstoned in client libraries and will not be removed. | ||
|
|
||
| - If backwards incompatible changes are made to an alpha or beta field after the warning period, the same changes will be made to the client libraries at that time. |
There was a problem hiding this comment.
These parts I'm a bit unsure of but it seemed like the best way to achieve consistency with our policies on alpha/beta features-- open to suggestions.
|
@tektoncd/core-maintainers I've directly assigned folks who have been more active in previous conversations on Go compat policies, but feedback is welcome from everyone! |
| When it is complete, the compatibility policy will be updated to include all of `pkg/apis`. | ||
|
|
||
| Pipelines contributors also plan to move all internal functionality in the entire [github.com/tektoncd/pipeline Go package](https://pkg.go.dev/github.com/tektoncd/pipeline) | ||
| into internal packages. This work is tracked in [issue #5679](https://github.com/tektoncd/pipeline/issues/5679). |
There was a problem hiding this comment.
Not related to this PR. But for the #5679, it seems that we haven't reached an alignment. I'm worried about the disadvantages we could get from it outweigh the benefits. It's hard to find out what functions should be internal, and it also limits the growth of tekton ecosystem by disallowing the usages of current public functions
There was a problem hiding this comment.
Thanks for the feedback! I retitled the issue. I think the purpose of the issue is to move functions that we don't want to expose externally into internal packages, so that it's possible to have a compat policy for everything else. It seems like the controversial part is what should be internal and what shouldn't be, but there was general consensus on moving internal functionality into internal packages. I agree this is challenging, but it seems to me like a good long-term goal.
api_compatibility_policy.md
Outdated
| - If support for an alpha CRD is dropped, its client library will not be removed until the last release with support for the CRD has reached its end of life. | ||
|
|
||
| - If support for a field is dropped, the field may also be removed from the client libraries; i.e. it is not guaranteed to be tombstoned. |
There was a problem hiding this comment.
What does it mean to "tombstone" a field? I can guess but I'm not entirely sure and I couldn't easily find a definition online. Perhaps it makes sense to link to a definition?
There was a problem hiding this comment.
I added a definition here, lmk if it is clear!
|
/retest |
tekton-robot
added
the
needs-rebase
tekton-robot
removed
the
needs-rebase
tekton-robot
added
the
approved
| @@ -74,3 +74,8 @@ how these affect your deprecation or timeline, ask the maintainers. | |||
| versions. Once you are reasonably confident that the field is no longer used | |||
| by supported servers (rule of thumb: target currently supported LTS servers), | |||
| it can safely be removed from client types. | |||
|
|
|||
| 4. Maintain backwards compatibility of Go libraries when possible. | |||
api_compatibility_policy.md
Outdated
|
|
||
| - Go structs representing stable fields may not change in breaking ways without a semver major version bump, even if the yaml/JSON API is unaffected. | ||
|
|
||
| - If support for a stable CRD is dropped (via a semver major version bump), the client libraries for this CRD will continue to be supported. |
There was a problem hiding this comment.
What does "supported" means in this context?
Does it mean we provide security patches, updates for newer versions of k8s etc?
How are we going to generate the clients for updates if the CRD is not there? Are we going to keep the CRD around and not serve it?
There was a problem hiding this comment.
thanks for the feedback-- clarified that "dropping" means "not serving" and "supporting" means keeping the client libraries preserved, but I don't think we would need to do anything like security patches.
This commit strengthens the stability policy for Tekton Pipelines' Go libraries for stable APIs, while allowing us to continue to evolve alpha APIs (and find a middle ground for beta APIs). Goals are: - maximize consistency - minimize confusion - clarify future work that needs to be done This inevitably involves some judgment calls that can be revisited over time. For a helpful reference on how Kubernetes handles unstable fields within stable APIs, see https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api_changes.md#adding-unstable-features-to-stable-versions. This is a helpful reference, but not all of these guidelines are applicable to Tekton given its current compatibility policies.
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: afrittoli, JeromeJu, vdemeester, Yongxuanzhang The full list of commands accepted by this bot can be found here. The pull request process is described here
Needs approval from an approver in each of these files:
Approvers can indicate their approval by writing |
|
/lgtm |
This commit strengthens the stability policy for Tekton Pipelines' Go libraries for stable APIs, while allowing us to continue to evolve alpha APIs (and find a middle ground for beta APIs).
Goals are:
This inevitably involves some judgment calls that can be revisited over time.
For a helpful reference on how Kubernetes handles unstable fields within stable APIs, see https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api_changes.md#adding-unstable-features-to-stable-versions. This is a helpful reference, but not all of these guidelines are applicable to Tekton given its current compatibility policies.
/kind misc
Closes #2748
Submitter Checklist
As the author of this PR, please check off the items in this checklist:
/kind <type>. Valid types are bug, cleanup, design, documentation, feature, flake, misc, question, tepRelease Notes