Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update Go Library Compatibility Policy #5773

Closed
wants to merge 2 commits into from
Closed

Update Go Library Compatibility Policy #5773

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
fca6bb3
Add GA API policy and describe feature gates
dibyom Oct 11, 2022
08e8cde
Add compatibility guidelines for Go library
dibyom Nov 10, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
131 changes: 97 additions & 34 deletions api_compatibility_policy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,10 @@
# API compatibility policy

This document proposes a policy regarding making API updates to the CRDs in this
This document proposes a policy regarding making updates to the Tekton API surface in this
repo. Users should be able to build on the APIs in these projects with a clear
idea of what they can rely on and what should be considered in progress and
therefore likely to change.

The use of `alpha`, `beta` and `GA` in this document is meant to correspond
roughly to
[the kubernetes API deprecation policies](https://kubernetes.io/docs/reference/using-api/deprecation-policy/#deprecating-a-flag-or-cli).

## What is the API?

The API is considered to consist of:
Expand All @@ -29,35 +25,95 @@ A backwards incompatible change would be a change that requires a user to update
existing instances of these CRDs in clusters where they are deployed and/or cause them
to change their CRD definitions to account for changes in the above.

## Alpha, Beta and GA
## CRD API Versions

The `apiVersion` field in a Tekton CRD determines whether the overall API (and its default behaviors) is considered to be in `alpha`, `beta`, or `GA`. The use of `alpha`, `beta` and `GA` (aka `stable`) follows the corresponding Kubernetes [API stages definition](https://kubernetes.io/docs/reference/using-api/#api-versioning).

Some of our CRDs and features are considered alpha, some are beta, and we are working
toward GA.
Within a stable CRD, certain opt-in features or API fields gated may be considered `alpha` or `beta`. Similarly, within a beta CRD, certain opt-in features may be considered `alpha`. See the section on Feature Gates for details.

The following CRDs are considered beta, though features may be introduced that are
alpha:

* `Task`
* `TaskRun`
* `ClusterTask`
* `Pipeline`
* `PipelineRun`

We are following [the Kubernetes definitions of these stages](https://kubernetes.io/docs/reference/using-api/api-overview/#api-versioning)
and we are following [the Kubernetes deprecation policy](https://kubernetes.io/docs/reference/using-api/deprecation-policy/).

* Alpha:
* These features may be dropped at any time, though you will be given at least
one release worth of warning.
* Beta:
* 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.
* You 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.
- `Task`
- `TaskRun`
- `ClusterTask`
- `Pipeline`
- `PipelineRun`

### Alpha CRDs

- For Alpha CRDs, the `apiVersion` contains the `alpha` (e.g. `v1alpha1`)

- Features may be dropped at any time, though you will be given at least one release worth of warning.

### Beta CRDs

- 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.

- 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.


### GA CRDs

- The `apiVersion` field of the CRD is `vX` where `X` is an integer.

- Stable API versions remain available for all future releases within a [semver major version](https://semver.org/#summary).

- Stable features may be marked as deprecated but may only be removed by incrementing the api version (i.e v1 to v2).

- We will not make any backwards incompatible changes to fields that are stable without incrementing the api version.

- Alpha and Beta features may be present within a stable API version. However, they will not be enabled by default and must be enabled by setting `enable-api-fields` to `alpha` or `beta`.

## Feature Gates

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.
* `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`.


| Feature Versions -> | v1 | beta | alpha |
|---------------------|----|------|-------|
| stable | x | | |
| beta | x | x | |
| alpha | x | x | x |


See the current list of [alpha features](https://github.com/tektoncd/pipeline/blob/main/docs/install.md#alpha-features) and [beta features](https://github.com/tektoncd/pipeline/blob/main/docs/install.md#beta-features).


### Alpha features

- 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

- Alpha features are reviewed for promotion to beta at a regular basis. However, there is no guarantee that they will be promoted to beta.

### Beta features

- 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)
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.

- For beta API versions, beta is the highest level of stability possible for any feature.

### GA/Stable features

- GA/Stable features are present in a [GA CRD](#ga-crds) only.

- GA/Stable features are enabled by default

- GA/Stable features will not be removed or changed in a backwards incompatible manner without incrementing the API version.

## Approving API changes

Expand Down Expand Up @@ -89,9 +145,16 @@ These changes must be approved by [more than half of the project OWNERS](OWNERS)
Tekton Pipelines [maintains a list of features that have been deprecated](https://github.com/tektoncd/pipeline/tree/main/docs/deprecations.md)
which includes the earliest date each feature will be removed.

## Go libraries compatibility policy
## Go Libraries

The following guidelines describe backwards incompatible changes and how they relate to release versioning for the public Go packages under `github.com/tektoncd/pipeline/pkg`.

Packages that are part of the Go client library for a particular CRD version should adhere to the stability guarantees for that version. This includes the Go structs for the API types in `pkg/apis/pipeline/$apiVersion` and the client libraries generated from those in `pkg/client`. This means:

- [Backwards incompatible changes](https://go.dev/blog/module-compatibility) such as changing or removing a field in a go struct in `pkg/apis/pipeline/v1alpha1` (or another alpha API) does not require a major version bump.

- Backwards incompatible changes in `pkg/apis/pipeline/v1beta1` (or another beta API) require providing a notice of the upcoming change for at least 3 releases before making the change. However, they do not require a major version bump.

- For `pkg/apis/pipeline/v1` (or any other stable APIs), any [backwards incompatible change](https://go.dev/blog/module-compatibility) will require a major version bump.

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.
For other packages, backwards incompatible changes are discouraged but they do not require a major version bump as long as they do not impact a user's YAML/JSON resource definitions.