-
Notifications
You must be signed in to change notification settings - Fork 1.8k
/
api_compatibility_policy.md
237 lines (148 loc) · 13.6 KB
/
api_compatibility_policy.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
# API compatibility policy
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.
## What is the API?
The API is considered to consist of:
- The structure of the CRDs including the `spec` and `status` sections, as well as:
- The ordering of the `steps` within the `status`
- The naming of the `step` containers within the `status`
- The labels propagated from `PipelineRuns` to `TaskRuns` and `TaskRuns` to `Pods`.
- The structure of the [directories created in executing containers by Tekton](docs/tasks.md#reserved-directories)
- The interfaces of the images that are built as part of Tekton Pipelines,
i.e. images in [cmd](https://github.com/tektoncd/pipeline/tree/main/cmd)
This policy is about changes to any of the above facets of the API.
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.
## 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).
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 stable, though features may be introduced that are
alpha or beta:
- `v1.Task`
- `v1.TaskRun`
- `v1.Pipeline`
- `v1.PipelineRun`
`v1beta1.CustomRun` is a beta CRD. Adding new fields to `CustomRun`
that all `CustomRun` controllers are required to support is considered a [backwards incompatible change](#backwards-incompatible-changes),
and follows the [beta policy](#beta-crds) for backwards incompatible changes.
`v1beta1.ResolutionRequest` is a beta CRD. Adding new fields to `ResolutionRequest`
that all resolvers are required to support is considered a [backwards incompatible change](#backwards-incompatible-changes),
and follows the [beta policy](#beta-crds) for backwards incompatible changes.
The following CRDs are deprecated. New features will not be added, but they will receive bug fixes.
- `v1beta1.Task`
- `v1beta1.ClusterTask`
- `v1beta1.TaskRun`
- `v1beta1.Pipeline`
- `v1beta1.PipelineRun`
To migrate to the v1 versions of these APIs, see [the migration guide](./docs/migrating-v1beta1-to-v1.md).
For more information on support windows, see the [deprecations table](./docs/deprecations.md).
### 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 receive bug fixes in new releases for a period of at least 9 months from the time a newer version is made available.
- As a special case, the `v1beta1` CRDs will not be removed until 1 year after they are deprecated,
because no stable API was available when they were created. The 9 month policy will apply to future beta APIs.
- 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
- 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. Alpha features will not be enabled by default and must be enabled by setting `enable-api-fields` to `alpha`. To disable beta features as well, set `enable-api-fields` to `stable`.
## 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` - 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, i.e. `beta` and `alpha` fields would not be enabled. TODO(#6592): Decouple feature stability from API stability.
* `beta` (default) - 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/additional-configs.md#alpha-features) and [beta features](https://github.com/tektoncd/pipeline/blob/main/docs/additional-configs.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/additional-configs.md#alpha-features)
- 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.
### Beta features
- Beta features are enabled by default and can be disabled by [setting `enable-api-fields` to `stable`](https://github.com/tektoncd/pipeline/blob/main/docs/additional-configs.md#beta-features).
- 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.
- 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.
### Feature Graduation Process
Features are first released as experimental in alpha, refined in beta, and finalized in stable releases.
#### Introducing an `alpha` feature
- When a feature is first introduced to Tekton, it will have the `alpha` stability level and be disabled by default.
- At this stage, users could choose to experiment with the feature. Feedback will be collected from users and it will help maintainers to determine whether to promote the feature to higher stability level or deprecate it.
#### Promoting a feature to `beta`
- After feedback of the usage of the alpha features, once the needs and motivations are validated, a feature could be promoted to `beta`. This stage is where features are further tested and refined.
- The dedicated feature flag for this feature will change the stability level for validation to `beta`. It will continue to be disabled by default.
#### Graduating a feature to `stable`
- This is the final stage of feature graduation process, where features are considered to be complete and ready to be released for the public.
- Once a feature has graduated to `stable`, it will be turned on by default.
## Approving API changes
API changes must be approved by [OWNERS](OWNERS). The policy is slightly different
for [additive changes](#additive-changes) vs.
[backwards incompatible changes](#backwards-incompatible-changes).
### Additive changes
Additive changes are changes that add to the API and do not cause problems for users
of previous versions of the API.
These changes must be approved by at least 2 [OWNERS](OWNERS).
### Backwards incompatible changes
Backwards incompatible changes change the API, e.g. by removing fields from a CRD
spec. These changes will mean that folks using a previous version of the API will need
to adjust their usage in order to use the new version.
Adding a new field to the CustomRun API that all CustomRun controllers are expected to support
is also a backwards incompatible change, as CustomRun controllers that were valid before the change
would be invalid after the change. Similarly, adding a new field to the ResolutionRequest API that
all resolvers are expected to support is also a backwards incompatible change.
These changes must be approved by [more than half of the project OWNERS](OWNERS)
(i.e. 50% + 1).
## Deprecated Features
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
In this context, "tombstoning" refers to retaining a field in client libraries, so that clients can continue to deserialize objects created with an older server version,
while disallowing new usage of the field.
### 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).
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).
Please follow these issues for developments in this area and any related changes to compatibility policies.
### 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 an alpha CRD stops being served, 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 a beta CRD stops being served, 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 a GA CRD stops being served (via a semver major version bump), the client libraries for this CRD will not be removed.
- If support for an alpha field is dropped, the field will be tombstoned in client libraries and will not be removed.
- If an alpha or beta field is renamed, the old field name will be tombstoned in client libraries and will not be removed.
### 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
Are you a Tekton contributor looking to make a backwards incompatible change?
Read more on additional considerations at [api-changes.md](./docs/developers/api-changes.md#deprecations).