Mark v1beta1 apis as deprecated

Now that v1 versions of Task, TaskRun, Pipeline, and PipelineRun are available and used as the storage version of these APIs, this commit marks the v1beta1 versions of these APIs as deprecated. This commit also clarifies that "support" for these APIs during the deprecation period means that they will receive bug fixes but not new features.
tektoncd · Jul 25, 2023 · 82a405a · 82a405a
1 parent 5cc5929
commit 82a405a
Show file tree

Hide file tree

Showing 9 changed files with 43 additions and 15 deletions.
diff --git a/api_compatibility_policy.md b/api_compatibility_policy.md
@@ -41,12 +41,21 @@ alpha or beta:
 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.ClusterTask` is a deprecated beta CRD. New features will not be added to `ClusterTask`.
-
 `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`)
@@ -61,7 +70,7 @@ and follows the [beta policy](#beta-crds) for backwards incompatible changes.
 
 - 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 be supported in new releases for a period of at least 9 months from the time a newer version is made available.
+- 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.
 

diff --git a/docs/deprecations.md b/docs/deprecations.md
@@ -26,6 +26,16 @@ The following features are deprecated but have not yet been removed.
 | [`pipelineRef.bundle` and `taskRef.bundle` are deprecated](https://github.com/tektoncd/pipeline/issues/5514)                                                                                                                 | v0.41.0                                                              | Alpha                                                                                                  | July 13, 2023                       |
 | [The `config-trusted-resources` configMap is deprecated](https://github.com/tektoncd/pipeline/issues/5852)                                                                                                                 | v0.45.0                                                              | Alpha                                                                                                  | v0.46.0                       |
 | [The `default-cloud-events-sink` setting in the `config-defaults` configMap is deprecated](https://github.com/tektoncd/pipeline/pull/6883) in favour of the new `config-events` configMap.                                                                                                                | v0.50.0                                                              | N/A                                                                                                  | v0.59.0                       |
+| [v1beta1 Tasks, TaskRuns, Pipelines, and PipelineRuns are deprecated in favor of v1](https://github.com/tektoncd/pipeline/issues/5541)                                                                                                                 | v0.50.0                                                              | Beta                                                                                                  | v0.62.0                       |
+
+### v1beta1 deprecation
+
+The v1beta1 versions of Task, TaskRun, Pipeline, and PipelineRun are deprecated in favor of the v1 versions of these APIs,
+as of release v0.50.0. Following the [beta CRD compatibility policy](../api_compatibility_policy.md#beta-crds),
+the earliest release the v1beta1 versions of these CRDs may be removed is 1 year later, or v0.62.0 (LTS).
+The v1beta1 client libraries will be retained until v0.62.0 has reached its end of life, 1 year later.
+Therefore, the earliest release the client libraries may be removed is v0.74.0, 12 months after v0.62.0.
+
 ## Removed features
 
 The features listed below have been removed but may still be supported in releases that have not reached their EOL.

diff --git a/docs/pipeline-api.md b/docs/pipeline-api.md
@@ -7741,6 +7741,7 @@ CustomRunStatus
 <div>
 <p>Pipeline describes a list of Tasks to execute. It expresses how outputs
 of tasks feed into inputs of subsequent tasks.</p>
+<p>Deprecated: Please use v1.Pipeline instead.</p>
 </div>
 <table>
 <thead>
@@ -7920,6 +7921,7 @@ the graph of Tasks declared in a Pipeline are executed; they specify inputs
 to Pipelines such as parameter values and capture operational aspects of the
 Tasks execution such as service account and tolerations. Creating a
 PipelineRun creates TaskRuns for Tasks in the referenced Pipeline.</p>
+<p>Deprecated: Please use v1.PipelineRun instead.</p>
 </div>
 <table>
 <thead>
@@ -8156,6 +8158,7 @@ PipelineRunStatus
 Pipeline using a set of inputs and producing a set of outputs. Tasks execute
 when TaskRuns are created that provide the input parameters and resources and
 output resources the Task requires.</p>
+<p>Deprecated: Please use v1.Task instead.</p>
 </div>
 <table>
 <thead>
@@ -8364,6 +8367,7 @@ the steps start and end after the steps complete.</p>
 <p>TaskRun represents a single execution of a Task. TaskRuns are how the steps
 specified in a Task are executed; they specify the parameters and resources
 used to run the steps in a Task.</p>
+<p>Deprecated: Please use v1.TaskRun instead.</p>
 </div>
 <table>
 <thead>

diff --git a/pkg/apis/pipeline/v1beta1/openapi_generated.go b/pkg/apis/pipeline/v1beta1/openapi_generated.go
diff --git a/pkg/apis/pipeline/v1beta1/pipeline_types.go b/pkg/apis/pipeline/v1beta1/pipeline_types.go
@@ -39,10 +39,12 @@ const (
 // +genclient:noStatus
 // +genreconciler:krshapedlogic=false
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
+// +k8s:openapi-gen=true
 
 // Pipeline describes a list of Tasks to execute. It expresses how outputs
 // of tasks feed into inputs of subsequent tasks.
-// +k8s:openapi-gen=true
+//
+// Deprecated: Please use v1.Pipeline instead.
 type Pipeline struct {
 	metav1.TypeMeta `json:",inline"`
 	// +optional

diff --git a/pkg/apis/pipeline/v1beta1/pipelinerun_types.go b/pkg/apis/pipeline/v1beta1/pipelinerun_types.go
@@ -38,14 +38,15 @@ import (
 // +genclient
 // +genreconciler:krshapedlogic=false
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
+// +k8s:openapi-gen=true
 
 // PipelineRun represents a single execution of a Pipeline. PipelineRuns are how
 // the graph of Tasks declared in a Pipeline are executed; they specify inputs
 // to Pipelines such as parameter values and capture operational aspects of the
 // Tasks execution such as service account and tolerations. Creating a
 // PipelineRun creates TaskRuns for Tasks in the referenced Pipeline.
 //
-// +k8s:openapi-gen=true
+// Deprecated: Please use v1.PipelineRun instead.
 type PipelineRun struct {
 	metav1.TypeMeta `json:",inline"`
 	// +optional

diff --git a/pkg/apis/pipeline/v1beta1/swagger.json b/pkg/apis/pipeline/v1beta1/swagger.json
@@ -680,7 +680,7 @@
       }
     },
     "v1beta1.Pipeline": {
-      "description": "Pipeline describes a list of Tasks to execute. It expresses how outputs of tasks feed into inputs of subsequent tasks.",
+      "description": "Pipeline describes a list of Tasks to execute. It expresses how outputs of tasks feed into inputs of subsequent tasks.\n\nDeprecated: Please use v1.Pipeline instead.",
       "type": "object",
       "properties": {
         "apiVersion": {
@@ -834,7 +834,7 @@
       }
     },
     "v1beta1.PipelineRun": {
-      "description": "PipelineRun represents a single execution of a Pipeline. PipelineRuns are how the graph of Tasks declared in a Pipeline are executed; they specify inputs to Pipelines such as parameter values and capture operational aspects of the Tasks execution such as service account and tolerations. Creating a PipelineRun creates TaskRuns for Tasks in the referenced Pipeline.",
+      "description": "PipelineRun represents a single execution of a Pipeline. PipelineRuns are how the graph of Tasks declared in a Pipeline are executed; they specify inputs to Pipelines such as parameter values and capture operational aspects of the Tasks execution such as service account and tolerations. Creating a PipelineRun creates TaskRuns for Tasks in the referenced Pipeline.\n\nDeprecated: Please use v1.PipelineRun instead.",
       "type": "object",
       "properties": {
         "apiVersion": {
@@ -2329,7 +2329,7 @@
       }
     },
     "v1beta1.Task": {
-      "description": "Task represents a collection of sequential steps that are run as part of a Pipeline using a set of inputs and producing a set of outputs. Tasks execute when TaskRuns are created that provide the input parameters and resources and output resources the Task requires.",
+      "description": "Task represents a collection of sequential steps that are run as part of a Pipeline using a set of inputs and producing a set of outputs. Tasks execute when TaskRuns are created that provide the input parameters and resources and output resources the Task requires.\n\nDeprecated: Please use v1.Task instead.",
       "type": "object",
       "properties": {
         "apiVersion": {
@@ -2515,7 +2515,7 @@
       }
     },
     "v1beta1.TaskRun": {
-      "description": "TaskRun represents a single execution of a Task. TaskRuns are how the steps specified in a Task are executed; they specify the parameters and resources used to run the steps in a Task.",
+      "description": "TaskRun represents a single execution of a Task. TaskRuns are how the steps specified in a Task are executed; they specify the parameters and resources used to run the steps in a Task.\n\nDeprecated: Please use v1.TaskRun instead.",
       "type": "object",
       "properties": {
         "apiVersion": {

diff --git a/pkg/apis/pipeline/v1beta1/task_types.go b/pkg/apis/pipeline/v1beta1/task_types.go
@@ -28,13 +28,14 @@ import (
 // +genclient:noStatus
 // +genreconciler:krshapedlogic=false
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
+// +k8s:openapi-gen=true
 
 // Task represents a collection of sequential steps that are run as part of a
 // Pipeline using a set of inputs and producing a set of outputs. Tasks execute
 // when TaskRuns are created that provide the input parameters and resources and
 // output resources the Task requires.
 //
-// +k8s:openapi-gen=true
+// Deprecated: Please use v1.Task instead.
 type Task struct {
 	metav1.TypeMeta `json:",inline"`
 	// +optional

diff --git a/pkg/apis/pipeline/v1beta1/taskrun_types.go b/pkg/apis/pipeline/v1beta1/taskrun_types.go
@@ -388,12 +388,13 @@ type CloudEventDeliveryState struct {
 // +genclient
 // +genreconciler:krshapedlogic=false
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
+// +k8s:openapi-gen=true
 
 // TaskRun represents a single execution of a Task. TaskRuns are how the steps
 // specified in a Task are executed; they specify the parameters and resources
 // used to run the steps in a Task.
 //
-// +k8s:openapi-gen=true
+// Deprecated: Please use v1.TaskRun instead.
 type TaskRun struct {
 	metav1.TypeMeta `json:",inline"`
 	// +optional