From 5c349d5d2751914d08a531681bbbafb2e31b8393 Mon Sep 17 00:00:00 2001 From: Lee Bernick Date: Mon, 29 Nov 2021 10:30:59 -0500 Subject: [PATCH] [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 --- teps/0096-pipelines-v1-api.md | 141 ++++++++++++++++++++++++++++++++++ teps/README.md | 1 + 2 files changed, 142 insertions(+) create mode 100644 teps/0096-pipelines-v1-api.md diff --git a/teps/0096-pipelines-v1-api.md b/teps/0096-pipelines-v1-api.md new file mode 100644 index 000000000..a70f0f547 --- /dev/null +++ b/teps/0096-pipelines-v1-api.md @@ -0,0 +1,141 @@ +--- +status: proposed +title: Pipelines V1 API +creation-date: '2021-11-29' +last-updated: '2021-12-07' +authors: +- '@lbernick' +- '@jerop' +- '@bobcatfish' +- '@vdemeester' +see-also: +- TEP-0033 +--- + +# TEP-0096: Pipelines V1 API + + +- [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) + + +## Summary + +Today, Tekton provides a Beta API and a deprecated Alpha API. +This TEP proposes a path to releasing Tekton Pipelines V1 to provide a stable API that users can rely on. +This TEP defines the Pipelines V1 API and stability policy, +the use cases we would like to support for Pipelines V1, and the 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. +New users may be waiting for V1 stability before using Tekton as their CI/CD platform in production, +and existing users will benefit from stability guarantees as well. + +### 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), +the feature gates [TEP-0033](./0033-tekton-feature-gates.md), and release tooling before V1 release. + +### Non Goals + +- Define the stability or V1 plans of other Tekton project. +- Discussion of software versioning. This TEP discusses what is needed to release a v1 (stable) API; +we expect to release a 1.0 software version shortly after. + +## 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](./0033-tekton-feature-gates.md). + +Tekton 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. +This policy states that API versions cannot be considered deprecated until they are +replaced by a version that is at least as stable (for example, v1beta1 can be considered deprecated when v1 is released). +A deprecated API version must continue to be supported for a length of time based on the following chart. + +| 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 +to a stable API version, meaning that a previous stable API version +must be supported for 12 months from when a new stable API version is created. Backwards incompatible API changes +must be accompanied by 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 | + +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, +even if it is part of a CRD that is considered stable. + +#### Examples +##### Removing an API field from a V1 CRD +Unless the field is controlled by a feature gate at an alpha or beta level of stability, this is a backwards-incompatible change. +Removing the field would require incrementing the API group to v2. +We could choose to release this change as part of a v2alpha1 or v2beta1 API before creating a v2 API. +v1 would not be considered deprecated until v2 is released, and would continue +to be supported for 12 months after that point. + +##### Adding an optional API field to a V1 CRD +Additive changes are backwards compatible and don't require incrementing the API version. +As described in [TEP-0033: Tekton Feature Gates](https://github.com/tektoncd/community/blob/main/teps/0033-tekton-feature-gates.md), +this field would be added as an alpha field to the CRD and gated behind the "enable-api-fields" flag. +It may then progress to beta and eventually to stable. + +##### Removing a flag-gated field or feature from a V1 CRD +An alpha or beta feature that is flag-gated and part of a v1 CRD may be +removed without incrementing the API version. + +##### Promoting a behavior flag +Changing the default behavior of Pipelines, including by promoting a behavior feature flag to opt-out, is a backwards incompatible change. + +However, as described in the [behavior flags example](https://github.com/tektoncd/community/blob/main/teps/0033-tekton-feature-gates.md#promoting-behavior-flags) +of TEP-0033: Feature Gates, Tekton's policy allows a behavior change to be updated from opt-in to opt-out without updating the API version. +A behavior can't be changed from opt-in to opt-out until 9 months after it is introduced to a beta API or 12 months after it is introduced to a stable API. +This is different from Kubernetes' policy, which would require creating a new API version to change a feature from opt-in to opt-out. + +### 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 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) diff --git a/teps/README.md b/teps/README.md index d05b57bc4..501c34cc6 100644 --- a/teps/README.md +++ b/teps/README.md @@ -231,3 +231,4 @@ This is the complete list of Tekton teps: |[TEP-0088](0088-result-summaries.md) | Tekton Results - Record Summaries | proposed | 2021-10-01 | |[TEP-0090](0090-matrix.md) | Matrix | proposed | 2021-11-08 | |[TEP-0094](0094-configuring-resources-at-runtime.md) | Configuring Resources at Runtime | proposed | 2021-11-08 | +|[TEP-0096](0096-pipelines-v1-api.md) | Pipelines V1 API | proposed | 2021-12-07 |