Add deprecation notes for developers. #6208
Conversation
These are not meant to be hard rules, but general tips / things to keep in mind for deprecations.
tekton-robot
added
release-note-none
tekton-robot
added
the
size/M
|
/cc @lbernick |
api_compatibility_policy.md
Outdated
| talk to older API servers. | ||
|
|
||
| A question to ask yourself is: "if I remove this field, can this client still | ||
| be used with the oldest supported LTS server?". If the answer is no, removing |
There was a problem hiding this comment.
Thanks @wlynch
Wondering if we shall suggest there to be a timeline that the earliest for those fields to be removed after defaulting the feature flag in one specific LTS as cycle out would probably mean 6 months?
There was a problem hiding this comment.
I think this depends on how the field was deprecated.
Most conservative is wait until the last LTS where a user could downgrade cycles out (worst case 1 yr from release). At minimum I'd probably consider it a separate deprecation event from the feature flag removal.
There are probably things you could do to reduce this. For example for the embedded status deprecation - what made this more painful was that the field might not be there. If we guaranteed earlier that the childRefs would always be present (since it would have been an additive backwards compatible change) and scoped the deprecation around the opt-out flag we probably could have removed the feature flag and the API field at the same time since we could guarantee childrefs to always be present in older LTS versions.
tekton-robot
added
the
approved
|
/test pull-tekton-pipeline-beta-integration-tests |
There was a problem hiding this comment.
Thank you @wlynch for clarifying the deprecation process!
I had clarifying questions, mainly wondering if the alpha compatibility policy should apply equally for opt-in and opt-out features (now that features will become opt-out earlier with more users using the feature by default)
| 1. (inital state) Return field A | ||
| 2. Introduce new field B with opt-in feature flag (disabled by default). | ||
| 3. Set feature flag to return both A and B in responses by default. | ||
| 4. Set feature flag to opt-in users by default and only return field B. | ||
| 5. Remove feature flag. |
There was a problem hiding this comment.
to clarify, are all these steps within the 9 months deprecation period? just want to be clear that we won't double the deprecation time
There was a problem hiding this comment.
There's no one right answer here - this is going to depend on what the change is, how the deprecation is done, and how disruptive it is.
You can make the argument that both the change in default behavior of a feature flag and the removal of a feature flag should be separate deprecation events. This is especially true for any deprecation that results in xor behavior.
I think there is room for shortcuts, so long as we have reasonable confidence that clients will be able to notice and adapt to changes - but I think how this can be done will differ on a case by case basis.
|
cc @tektoncd/core-maintainers |
I think Kubernetes has a reasonable policy for this that we may be able to borrow - https://kubernetes.io/docs/reference/command-line-tools-reference/feature-gates/#feature-stages tl;dr alpha features == opt in |
@wlynch I like that K8s policy, let's borrow it! What do other @tektoncd/core-maintainers think? Also can we make this a tekton-wide policy (in tektoncd/community), instead of just for tektoncd/pipeline? |
This is probably going to be a little tricky since I don't think there is a consistent definition of alpha/beta/GA across projects (which is by design - not every project wants to adopt the same deprecation policy as pipelines), but you're welcome to! Let's lead by example here first - we can add to community later. |
|
Thought that definitions of alpha/beta/GA in TEP-0033 applied across all projects, but sounds good to me to learn from adoption in this project first |
|
|
||
| See https://github.com/golang/go/wiki/Deprecated for more details. | ||
|
|
||
| 3. Tombstone API fields before removal. |
|
Anything blocking submission here? |
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: dibyom, JeromeJu, lbernick 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 |
Changes
Add deprecation notes for developers.
These are not meant to be hard rules, but general tips / things to keep in mind for deprecations.
/kind documentation
Submitter Checklist
As the author of this PR, please check off the items in this checklist:
functionality, content, code)
/kind <type>. Valid types are bug, cleanup, design, documentation, feature, flake, misc, question, tepRelease Notes