[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

@@ -0,0 +1,130 @@
+---
+status: proposed
+title: Pipelines V1 Release
+creation-date: '2021-11-29'
+last-updated: '2021-11-29'
+authors:
+- '@lbernick'
+- '@jerop'
+- '@bobcatfish'
+- '@vdemeester'
+see-also:
+- TEP-0033
+---
+
+# 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.
+- Define stability policies for aspects of Pipelines unrelated to the API, such as performance, dogfooding,
+release automation, and testing and debugging features.
+- Discussion of software versioning. This TEP discusses only API versioning. 
+
+## 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).
+
+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
+This is a backwards-incompatible change and 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
+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.
+The field may progress to beta and then to stable without incrementing the API version.
+
+##### 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.
+
+### 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)

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 |