From b792714e0dce68647aa6f2e6404943d76a9820b4 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-release.md | 111 ++++++++++++++++++++++++++++++ teps/README.md | 1 + 2 files changed, 112 insertions(+) create mode 100644 teps/0096-pipelines-v1-release.md diff --git a/teps/0096-pipelines-v1-release.md b/teps/0096-pipelines-v1-release.md new file mode 100644 index 000000000..2fc25c22f --- /dev/null +++ b/teps/0096-pipelines-v1-release.md @@ -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 + + +- [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 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) diff --git a/teps/README.md b/teps/README.md index d05b57bc4..6198fd1ce 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-release.md) | Pipelines V1 Release | proposed | 2021-11-29 |