[Checklist] How to make sure apiVersion migration is comprehensive

[JeromeJu]

This is to keep tracks of the issues during the process of migration from v1beta1 to v1. And this aims to spot and avoid the "gotchas" alongside each stage. And hopefully this would also note down the difference between the last migration from v1alpha1 to v1beta1 and have some sort of checklist for future migrations.

Checklist

Stage of creating CRDs of newer apiVersion:

• Reach consensus of deprecation of fields and the respective handling of them in both apiVersions

Stage of serving new version of CRD:

• Integration tests for conversion
• Example tests with the new clients
• Conversion unit tests covering all fields

---

• How to catch the issue of STATUS:
  • Thoroughly testing:
    The examples_tests needs to be updated for v1clients
• Conversion of bundles fixes:
  • Integration tests needs to be introduced before serving

Gotchas:
Kubernetes always present the highest priority with kubectl at
https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning/

Diff:

• Conversion of STATUS of PR and TR in v1alpha1 to v1beta1, the status are shared (just copied from v1)

[JeromeJu]

[WIP] Comparing the process for v1beta1 -> v1 and v1alpha1 -> v1beta1

v1beta1 -> v1:

• Add CRD Golang structs
  • Add V1 Task Golang structs #5125
  • Add V1 Pipeline Golang structs #5219
  • Add V1 TaskRun Golang structs #5264
  • Add V1 PipelineRun Golang struct #5324
• Add conversion
  • Add conversion for v1 Task #5202
  • Add conversion for v1 Pipeline #5258
  • Add conversion for v1 TaskRun #5274
  • Add conversion for v1 PipelineRun #5426
• Handle deprecated fields in conversion
  • V1: Add conversion for Task.Resources #5253
  • V1: Add conversion for Pipeline.Resources #5331
  • V1: Add conversion for TaskRun.Resources #5378
  • V1: Add conversion for TaskRunSpec.TaskRef.Bundle #5381
  • V1: add conversion for PipelineRunSpec.PipelineRef.Bundle #5477
• Add CRD to webhook and config
  • Add V1 version to Task CRD #5234
  • Add V1 version of PipelineRun CRD #5464
  • Add V1 version of TaskRun CRD #5379
  • Add V1 version of PipelineRun CRD #5464
• Add migration doc
  • Doc about migrating from v1beta1 to v1 #5415
• Release CRD
  • V1 CRD release #5579

Comparing with what's done for v1alpha1 -> v1beta1:

• Change the storage version to v1beta1 types #2577

[JeromeJu]

Post-mortem:

• Compare the Cutoff of V1 CRD release

• [release-v0.43.x] Fix embedded-status conversion for PipelineRuns #5974

• [release-v0.43.x] Register informers for v1 TaskRun and PipelineRun #5948

• v1 software release:

• Comparing with v1alpha1->v1beta1 swap, we have experienced more obstacles/blockers while switching from v1beta1->v1

  • we didn't have feature flags at that time, so we didn't need to deal with Decoupling API versioning and Feature versioning for features turned on by default #6592.
  • we had introduced features/ flags that needs to be cleanup before migrating
    • pipelineRunStatus Migration
    • pipelineResources Migration
    • version validation (coupling of apiVersion and feature version)

[dibyom]

Nice @JeromeJu we should update https://github.com/tektoncd/pipeline/blob/main/docs/developers/api-versioning.md#adding-a-new-api-version-to-a-pipelines-crd with this when done!