diff --git a/README.md b/README.md index ab3ed97b..e3ed3c62 100644 --- a/README.md +++ b/README.md @@ -145,6 +145,7 @@ The Temporal Worker Controller eliminates this operational overhead by automatin | Document | Description | |-------------------------------------------------------------|-----------------------------------------------------------------------| +| [Releases](docs/release.md) | How we version and release the controller and Helm Chart | | [Migration Guide](docs/migration-to-versioned.md) | Step-by-step guide for migrating from traditional deployments | | [Reversion Guide](docs/migration-to-unversioned.md) | Step-by-step guide for migrating back to unversioned deployment | | [CD Rollouts](docs/cd-rollouts.md) | Helm, kubectl, ArgoCD, and Flux integration for steady-state rollouts | diff --git a/docs/release.md b/docs/release.md new file mode 100644 index 00000000..551cd2ac --- /dev/null +++ b/docs/release.md @@ -0,0 +1,64 @@ +# Releases + +This document explains our thinking around Releases of Temporal Worker +Controller and associated Helm Charts. + +A Release is a coordination point for publishing a versioned set of artifacts. +Each Release has a Github Release page which describes the changes in the +Release and the artifacts associated with it. + +A Release Tag is simply the string name given to the Release. + +In the Temporal Worker Controller project, we cut two different kinds of Releases: + +* **Application Release**: contains the Temporal Worker Controller container image. +* **Chart Release**: contains the Helm Charts that install the Temporal Worker + Controller and the Custom Resource Definitions (CRDs) used by the controller. + +These different kinds of Releases are on different cadences and use different +version numbering. + +## Application Releases + +Application Releases refer to the Temporal Worker Controller code and the +`temporalio/temporal-worker-controller` container image artifacts. + +Release Tags for official Application Releases will always use Semantic Version +strings, e.g. `v1.42.1`. + +We bump the minor version number of the Application Release version when new +features are added **to the controller code itself**. + +Likewise, We bump the patch version number of the Application Release version +when bug fixes are added to the controller code itself. + +> **IMPORTANT**: Changes to the Application Release version string's minor and +> patch versions **do not imply a change to either the Helm Chart Release +> version or the APIVersion of the CRDs supported by the controller**. + +## Chart Releases + +Chart Releases refer to the two Helm Charts that install the Temporal Worker +Controller and manage the Custom Resource Definitions (CRDs) used by the +controller. + +Release Tags for official Chart Releases are prefixed with the string `helm-` +and the Semantic Version string for the Chart Release, e.g. `helm-v0.24.0`. + +**The major version of the Semantic Version string for the Chart Release refers +to the APIVersion of the CRDs.** + +While the APIVersion of the CRDs is on the `v1alpha` series, the major version +of the Semantic Version string for the Chart Release will remain on `v0`. + +When the APIVersion of the CRDs moves to the `v1` series, the major version of +the Semantic Version string for the Chart Release will be bumped to `v1`. + +The minor version of the Semantic Version string for the Chart Release is +bumped when we change the structure of the Helm Chart itself -- by adding, +removing or modifying `values.yaml` options or adding, removing or modifying +Kubernetes resources in the `templates/` directory. + +The patch version of the Semantic Version string for the Chart Release is +bumped when we release a new Application Release and update the `Chart.yaml`'s +`appVersion` field to point to a new Application Release.