From a3c1695f88017471381dfae0da7bfcf9057039b1 Mon Sep 17 00:00:00 2001 From: Lee Bernick Date: Fri, 2 Jun 2023 15:26:40 -0400 Subject: [PATCH] Update Go compatibility policy 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. --- api_compatibility_policy.md | 62 ++++++++++++++++++++++++++++------ docs/developers/api-changes.md | 5 +++ 2 files changed, 57 insertions(+), 10 deletions(-) diff --git a/api_compatibility_policy.md b/api_compatibility_policy.md index 12253439fbe..7e53dbb0f2e 100644 --- a/api_compatibility_policy.md +++ b/api_compatibility_policy.md @@ -53,12 +53,11 @@ and follows the [beta policy](#beta-crds) for backwards incompatible changes. - The `apiVersion` field of the CRD contains contain `beta` (for example, `v1beta1`). -- These features will not be dropped, though the details may change. - -- Any [backwards incompatible changes](#backwards-incompatible-changes) must be introduced in a backwards compatible manner first, with a deprecation warning in the release notes and migration instructions. +- Any [backwards incompatible changes](#backwards-incompatible-changes) must be introduced in a backwards compatible manner first, with a deprecation warning in the release notes and migration instructions. - Users will be given at least 9 months to migrate before a backward incompatible change is made. This means an older beta API version will continue to be supported in new releases for a period of at least 9 months from the time a newer version is made available. +- Alpha features may be present within a beta API version. However, they will not be enabled by default and must be enabled by setting `enable-api-fields` to `alpha`. ### GA CRDs @@ -76,7 +75,7 @@ and follows the [beta policy](#beta-crds) for backwards incompatible changes. CRD API versions gate the overall stability of the CRD and its default behaviors. Within a particular CRD version, certain opt-in features may be at a lower stability level as described in [TEP-33](https://github.com/tektoncd/community/blob/main/teps/0033-tekton-feature-gates.md). These fields may be disabled by default and can be enabled by setting the right `enable-api-fields` feature-flag as described in TEP-33: -* `stable` (default) - This value indicates that only fields of the highest stability level are enabled; For `beta` CRDs, this means only beta stability fields are enabled, i.e. `alpha` fields are not enabled. For `GA` CRDs, this means only `GA` fields are enabled by defaultd, i.e. `beta` and `alpha` fields would not be enabled. +* `stable` (default) - This value indicates that only fields of the highest stability level are enabled; For `beta` CRDs, this means only beta stability fields are enabled, i.e. `alpha` fields are not enabled. For `GA` CRDs, this means only `GA` fields are enabled by default, i.e. `beta` and `alpha` fields would not be enabled. TODO(#6592): Decouple feature stability from API stability. * `beta` - This value indicates that only fields which are of `beta` (or greater) stability are enabled, i.e. `alpha` fields are not enabled. * `alpha` - This value indicates that fields of all stability levels are enabled, specifically `alpha`, `beta` and `GA`. @@ -95,7 +94,7 @@ See the current list of [alpha features](https://github.com/tektoncd/pipeline/bl - Alpha feature in beta or GA CRDs are disabled by default and must be enabled by [setting `enable-api-fields` to `alpha`](https://github.com/tektoncd/pipeline/blob/main/docs/install.md#alpha-features) -- These features may be dropped or backwards incompatible changes made at any time though will be given at least one release worth of warning +- These features may be dropped or backwards incompatible changes made at any time, though one release worth of warning will be provided. - Alpha features are reviewed for promotion to beta at a regular basis. However, there is no guarantee that they will be promoted to beta. @@ -103,7 +102,9 @@ See the current list of [alpha features](https://github.com/tektoncd/pipeline/bl - Beta features in GA CRDs are disabled by default and must be enabled by [setting `enable-api-fields` to `beta`](https://github.com/tektoncd/pipeline/blob/main/docs/install.md#beta-features). In beta API versions, beta features are enabled by default. -- Beta features may be deprecated or changed in a backwards incompatible way by following the same process as [Beta CRDs](#beta-crds) +- These features will not be dropped, though the details may change. + +- Beta features may be changed in a backwards incompatible way by following the same process as [Beta CRDs](#beta-crds) i.e. by providing a 9 month support period. - Beta features are reviewed for promotion to GA/Stable on a regular basis. However, there is no guarantee that they will be promoted to GA/stable. @@ -150,10 +151,51 @@ which includes the earliest date each feature will be removed. ## Go libraries compatibility policy -Tekton Pipelines may introduce breaking changes to its Go client libraries, as long as these changes -do not impact users' yaml/json CRD definitions. For example, a change that renames a field of a CRD -would need to follow the policy on [backwards incompatible changes](#backwards-incompatible-changes), -but a change that renames the Go struct type for that field is allowed. +### Covered parts of the codebase + +The compatibility policy for the [github.com/tektoncd/pipeline Go package](https://pkg.go.dev/github.com/tektoncd/pipeline) currently only covers +Go structs representing CRDs in `pkg/apis`, the generated client libraries in `pkg/client`, and the [resolver interface](https://github.com/tektoncd/pipeline/blob/main/pkg/resolution/resolver/framework/interface.go). +Backwards compatibility for other parts of the codebase is on a best-effort basis. + +Pipelines contributors are working on modularizing `pkg/apis`, so that clients only need to import a minimal set of dependencies. +This work is tracked in [issue #6483](https://github.com/tektoncd/pipeline/issues/6483). +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). +When it is complete, the compatibility policy will be updated to include all of `github.com/tektoncd/pipeline`. + +### Alpha CRDs + +- Go structs representing alpha CRDs may change in breaking ways at any time. If the change impacts the yaml/JSON API, we will provide one release of warning. + +- 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. + +### Beta CRDs + +- Go structs representing beta CRDs may change in breaking ways if the yaml/JSON API is unaffected. + +- If support for a beta 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 an alpha field is dropped, the field will be tombstoned in client libraries and will not be removed until the last release with support for the field. + +### Stable CRDs + +- 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. + +- 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. + +### Resolver Interface + +Remote resolution is currently a beta feature. [Issue #6579](https://github.com/tektoncd/pipeline/issues/6579) tracks promoting resolution to stable. +Backwards compatibility for the [resolver interface](https://github.com/tektoncd/pipeline/blob/main/pkg/resolution/resolver/framework/interface.go) +is currently on a best-effort basis. When remote resolution is promoted to stable, backwards incompatible changes may not be made to the resolver interface. ## Notes for Developers diff --git a/docs/developers/api-changes.md b/docs/developers/api-changes.md index 58fe6ce038d..cbe00567ce6 100644 --- a/docs/developers/api-changes.md +++ b/docs/developers/api-changes.md @@ -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. + + [Keeping Your Modules Compatible](https://go.dev/blog/module-compatibility) + offers some helpful suggestions.