From e5c1340adaf0e777bf07103f5d3d33cb2caad6d4 Mon Sep 17 00:00:00 2001 From: Jay Pipes Date: Wed, 22 Apr 2026 12:00:24 -0400 Subject: [PATCH] doc: release policy and versioning Adds documentation that explains how we think about releases of the application and Helm Charts and when we will bump major, minor and patch versions for both Application and Chart Releases. Issue #264 Signed-off-by: Jay Pipes --- README.md | 1 + docs/release.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 65 insertions(+) create mode 100644 docs/release.md 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.