-
Notifications
You must be signed in to change notification settings - Fork 222
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[Problem Statement] TEP-0096: Pipelines V1 Release
This commit defines the problem statement for a stable release of Tekton pipelines. It also describes the current Pipelines deprecation policy and proposes a deprecation policy for a stable release of Pipelines. Co-authored-by: Jerop Kipruto jerop@google.com
- Loading branch information
Showing
2 changed files
with
112 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,111 @@ | ||
| --- | ||
| status: proposed | ||
| title: Pipelines V1 Release | ||
| creation-date: '2021-11-29' | ||
| last-updated: '2021-11-29' | ||
| authors: | ||
| - '@lbernick' | ||
| - '@jerop' | ||
| - '@bobcatfish' | ||
| - '@vdemeester' | ||
| --- | ||
|
|
||
| # TEP-0096: Pipelines V1 Release | ||
|
|
||
| <!-- toc --> | ||
| - [Summary](#summary) | ||
| - [Motivation](#motivation) | ||
| - [Goals](#goals) | ||
| - [Non-Goals](#non-goals) | ||
| - [Background](#background) | ||
| - [Proposal](#proposal) | ||
| - [V1 Stability and Deprecation Policy](#v1-stability-and-deprecation-policy) | ||
| - [API Definition](#api-definition) | ||
| - [Use Cases](#use-cases) | ||
| - [References](#references) | ||
| <!-- /toc --> | ||
|
|
||
| ## Summary | ||
|
|
||
| Today, Tekton provides Alpha and Beta APIs. | ||
| This TEP proposes a path to releasing Tekton Pipelines V1 to provide a stable API that users can rely on. | ||
| This TEP documents the API definition and stability policy for Pipelines V1, | ||
| defines the use cases we would like to support for Pipelines V1, and discusses features needed to support these use cases. | ||
|
|
||
| ## Motivation | ||
|
|
||
| To become the industry standard, cloud-native CI/CD platform, | ||
| Tekton must provide users with a stable API they can rely on. | ||
| Some users may be waiting for V1 stability before deciding to use Tekton. | ||
|
|
||
| ### Goals | ||
|
|
||
| - Define stability policy for Pipelines V1. | ||
| - Define supported and unsupported use cases for Pipelines V1. | ||
| - Define criteria for a feature to be "required" or "optional" for Pipelines V1. | ||
| - Define what updates, if any, are needed to the [Pipelines API definition](https://github.com/tektoncd/pipeline/blob/main/api_compatibility_policy.md#what-is-the-api) before V1 release. | ||
|
|
||
| ### Non Goals | ||
|
|
||
| - Define the stability or V1 plans of other Tekton project. | ||
| - Discuss aspects of Pipelines unrelated to the API, such as performance, dogfooding, release automation, | ||
| and testing and debugging features. | ||
|
|
||
| ## Background | ||
|
|
||
| Tekton currently uses Kubernetes' [API versioning guidelines](https://kubernetes.io/docs/reference/using-api/api-overview/#api-versioning) | ||
| to define API stability levels, as described in the [compatibility policy](https://github.com/tektoncd/pipeline/blob/main/api_compatibility_policy.md#alpha-beta-and-ga). | ||
|
|
||
| Tekton API components may contain features at a lower level of stability, gated behind feature flags, | ||
| as described in [TEP-0033: Tekton Feature Gates](https://github.com/tektoncd/community/blob/main/teps/0033-tekton-feature-gates.md). | ||
|
|
||
| Both Tekton and Kubernetes software releases use [semantic versioning](https://semver.org), but Tekton does not follow | ||
| Kubernetes' guidelines for [release versioning](https://github.com/kubernetes/sig-release/blob/master/release-engineering/versioning.md). | ||
| Specifically, Tekton does not include release tags containing "alpha", "beta", or "rc". | ||
|
|
||
| Tekton also follows Kubernetes' [deprecation policy](https://kubernetes.io/docs/reference/using-api/deprecation-policy/). | ||
| However, while Kubernetes defines stability periods in terms of months or releases, whichever is longer, | ||
| Tekton defines stability periods only in terms of months. | ||
|
|
||
| | API Version | Kubernetes Deprecation Policy | Tekton Deprecation Policy | | ||
| |:----------- |:----------------------------- |:------------------------- | | ||
| | Alpha | 0 releases | 0 months | | ||
| | Beta | 9 months or 3 releases | 9 months | ||
|
|
||
| ## Proposal | ||
|
|
||
| ### V1 Stability and Deprecation Policy | ||
|
|
||
| Tekton will continue to follow the Kubernetes [API versioning guidelines](https://kubernetes.io/docs/reference/using-api/api-overview/#api-versioning) and [deprecation policy](https://kubernetes.io/docs/reference/using-api/deprecation-policy/). Users will have at least 12 months to upgrade to backwards incompatible changes, meaning that a previous API version must be supported for 12 months from when a new API version is created. Backwards incompatible API changes must be accompanied by a major version software release, deprecation warnings, and migration instructions from the previous version. | ||
|
|
||
| | API Version | Kubernetes Deprecation Policy | Tekton Deprecation Policy | | ||
| |:----------- |:----------------------------- |:------------------------- | | ||
| | Alpha | 0 releases | 0 months | | ||
| | Beta | 9 months or 3 releases | 9 months | | ||
| | V1 | 12 months or 3 releases | 12 months | | ||
|
|
||
| For example, if an API element is removed from a Pipelines V1 CRD, the CRD version would become V2, | ||
| and the software version would be updated from 1.x.y to 2.0.0. | ||
|
|
||
| No changes are proposed to [TEP-0033: Tekton Feature Gates](https://github.com/tektoncd/community/blob/main/teps/0033-tekton-feature-gates.md), | ||
| meaning that features gated behind flags will follow their respective stability policies. | ||
| For example, a flag-gated alpha feature may be removed at any time without incrementing the CRD version or software major version, | ||
| even if it is part of a CRD that is considered stable. | ||
|
|
||
| ### API Definition | ||
|
|
||
| ## Use Cases | ||
|
|
||
| ### V1 Supported Use Cases | ||
|
|
||
| ### V1 Unsupported Use Cases | ||
|
|
||
| ## References | ||
|
|
||
| - [Doc: Beta plan and policy](https://docs.google.com/document/d/1H8I2Rk4kLdQaR4mV0A71Qbk-1FxXFrmvisEAjLKT6H0) | ||
| - [Issue: Towards V1 API](https://github.com/tektoncd/pipeline/issues/3548) | ||
| - [Tekton Pipelines API Compatibility Policy](https://github.com/tektoncd/pipeline/blob/main/api_compatibility_policy.md#alpha-beta-and-ga) | ||
| - [Kubernetes API Versioning](https://kubernetes.io/docs/reference/using-api/api-overview/#api-versioning) | ||
| - [Kubernetes Release Versioning](https://github.com/kubernetes/sig-release/blob/master/release-engineering/versioning.md) | ||
| - [Kubernetes Deprecation Policy](https://kubernetes.io/docs/reference/using-api/deprecation-policy/) | ||
| - [TEP-0033: Tekton Feature Gates](https://github.com/tektoncd/community/blob/main/teps/0033-tekton-feature-gates.md) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters