Releasing k8ssandra-operator

How to perform releases of k8ssandra-operator

Prerequisites

yq installed.

With MacOS / Homebrew:

brew install yq

Major / Minor Release

Preliminary steps

Create these environment variables, we’ll reference them throughout the rest of this section:

the Major.minor coordinates of the version we are about to release:
```
export RELEASED_MAJOR_MINOR=1.6
```
the Major.minor coordinates of the next version on the main branch (usually this will be the next minor, but there could also be a major bump, like 2.0):
```
export NEXT_MAJOR_MINOR=1.7
```
the name of your Git remote for k8ssandra/k8ssandra-operator:
```
export GIT_REMOTE=origin
```

In your local k8ssandra-operator clone, check out the main branch and make sure it’s up-to-date:

git checkout main
git pull ${GIT_REMOTE?} main

Create the release branch

git checkout -b release/${RELEASED_MAJOR_MINOR?}

Update the changelog

Edit CHANGELOG/CHANGELOG-${RELEASED_MAJOR_MINOR?}.md and replace the ## unreleased section with the new release version and date (keep the ## unreleased section above it).

The diff should look like this:

@@ -15,6 +15,8 @@ When cutting a new release, update the `unreleased` heading to the tag being gen

 ## unreleased

+## v1.6.0 - 2023-03-10
+
 * [CHANGE] [#907](https://github.com/k8ssandra/k8ssandra-operator/issues/907) Update to cass-operator v1.15.0, remove Vector sidecar, instead use cass-operator's server-system-logger Vector agent and only modify its config

Commit the changes:

git add CHANGELOG/CHANGELOG-${RELEASED_MAJOR_MINOR?}.md
git commit -m"Update changelog for v${RELEASED_MAJOR_MINOR?}.0"

Check that the documentation builds

cd docs

npm install
npm run clean
npm run build:production

cd ..

If there are any errors, fix them and commit them on the release branch.

Create the release commit

Update the image tag in the default kustomization:

yq e -i '.images[0].newTag="v"+env(RELEASED_MAJOR_MINOR)+".0"' config/deployments/default/kustomization.yaml

The diff should look like this:

@@ -8,5 +8,4 @@ resources:

 images:
   - name: k8ssandra/k8ssandra-operator
-    newTag: latest
-
+    newTag: v1.6.0

Update the version in the release chart:

yq e -i '.version=env(RELEASED_MAJOR_MINOR)+".0"' charts/k8ssandra-operator/Chart.yaml

The diff should look like this:

@@ -3,7 +3,7 @@ name: k8ssandra-operator
 description: |
   Kubernetes operator which handles the provisioning and management of K8ssandra clusters.
 type: application
-version: 1.6.0-SNAPSHOT
+version: 1.6.0
 dependencies:
   - name: k8ssandra-common
     version: 0.29.0

Commit:

git add config/deployments/default/kustomization.yaml charts/k8ssandra-operator/Chart.yaml
git commit -m"Release v${RELEASED_MAJOR_MINOR?}.0"

Push the changes:

git push ${GIT_REMOTE?} release/${RELEASED_MAJOR_MINOR?}

Wait for the GitHub Actions workflows to complete.

Tag the release

git tag v${RELEASED_MAJOR_MINOR?}.0
git push ${GIT_REMOTE?} v${RELEASED_MAJOR_MINOR?}.0

Wait for the GitHub Actions workflows to complete.

Create the release in GitHub

Go to the New Release page.

click on “Choose a tag” and select the tag you just pushed, e.g. v1.6.0.
for the release title, use the name of the tag, e.g. “v1.6.0”.
for the description, just copy the contents for this version from the changelog.

Click on “Publish release”.

Prepare the branch for the next patch release

Update the image tag in the default kustomization:

yq e -i '.images[0].newTag=env(RELEASED_MAJOR_MINOR)+"-latest"' config/deployments/default/kustomization.yaml

The diff should look like this:

@@ -8,5 +8,4 @@ resources:

 images:
   - name: k8ssandra/k8ssandra-operator
-    newTag: v1.6.0
-
+    newTag: 1.6-latest

Update the version in the release chart:

yq e -i '.version=env(RELEASED_MAJOR_MINOR)+".1-SNAPSHOT"' charts/k8ssandra-operator/Chart.yaml

The diff should look like this:

@@ -3,7 +3,7 @@ name: k8ssandra-operator
 description: |
   Kubernetes operator which handles the provisioning and management of K8ssandra clusters.
 type: application
-version: 1.6.0
+version: 1.6.1-SNAPSHOT
 dependencies:
   - name: k8ssandra-common
     version: 0.29.0

Commit the changes:

git add config/deployments/default/kustomization.yaml charts/k8ssandra-operator/Chart.yaml
git commit -m"Prepare next patch release"

Update the main branch

Merge with the “ours” strategy (none of the changes are applied):

git checkout main
git merge release/${RELEASED_MAJOR_MINOR?} -s ours

Then cherry-pick the changelog update, as well as any fixes you might have done on the branch (docs, failing tests, etc):

git cherry-pick -n <your commit SHA-1s...>

DO NOT cherry-pick the “Release vx.x.x” or “Prepare next patch release” commits.

Amend the merge commit with your cherry-picks:

git add .
git commit --amend --no-edit

Update the version in the release chart:

yq e -i '.version=env(NEXT_MAJOR_MINOR)+".0-SNAPSHOT"' charts/k8ssandra-operator/Chart.yaml

The diff should look like this:

@@ -3,7 +3,7 @@ name: k8ssandra-operator
 description: |
   Kubernetes operator which handles the provisioning and management of K8ssandra clusters.
 type: application
-version: 1.6.0-SNAPSHOT
+version: 1.7.0-SNAPSHOT
 dependencies:
   - name: k8ssandra-common
     version: 0.29.0

Create a new blank changelog file:

cat > CHANGELOG/CHANGELOG-${NEXT_MAJOR_MINOR?}.md << 'EOF'
# Changelog

Changelog for the K8ssandra Operator, new PRs should update the `unreleased` section below with entries describing the changes like:

```markdown
* [CHANGE]
* [FEATURE]
* [ENHANCEMENT]
* [BUGFIX]
* [DOCS]
* [TESTING]
```

When cutting a new release, update the `unreleased` heading to the tag being generated and date, like `## vX.Y.Z - YYYY-MM-DD` and create a new placeholder section for  `unreleased` entries.

## unreleased
EOF

Commit the changes:

git add charts/k8ssandra-operator/Chart.yaml CHANGELOG/CHANGELOG-${NEXT_MAJOR_MINOR?}.md
git commit -m"Prepare next release"

Push all the changes:

git push ${GIT_REMOTE?} main release/${RELEASED_MAJOR_MINOR?} --atomic

Patch Release

Preliminary steps

Create these environment variables, we’ll reference them throughout the rest of this section:

the Major.minor coordinates of the version we are about to release:
```
export RELEASED_MAJOR_MINOR=1.6
```
the full coordinates of the version we are about to release:
```
export RELEASED_FULL=1.6.1
```
the full coordinates of the next version on the release branch:
```
export NEXT_FULL=1.6.2
```
the name of your Git remote for k8ssandra/k8ssandra-operator:
```
export GIT_REMOTE=origin
```

In your local k8ssandra-operator clone, make sure the main and release branches are up-to-date, and switch to the release branch:

git checkout main
git pull ${GIT_REMOTE?} main

git checkout release/${RELEASED_MAJOR_MINOR?}
git pull ${GIT_REMOTE?} release/${RELEASED_MAJOR_MINOR?}

Cherry-pick the changes from main

Select the commits to include from the main branch:

git cherry-pick <SHA1...>

Note that we don’t use the -n option here, we want to keep them as individual commits. Also, make sure that you copy the changelog entries to the file corresponding to the current release (CHANGELOG/CHANGELOG-${RELEASED_MAJOR_MINOR?}.md).

Update the changelog

Edit CHANGELOG/CHANGELOG-${RELEASED_MAJOR_MINOR?}.md and replace the ## unreleased section with the new release version and date (keep the ## unreleased section above it).

The diff should look like this:

@@ -15,6 +15,8 @@ When cutting a new release, update the `unreleased` heading to the tag being gen

 ## unreleased

+## v1.6.1 - 2023-04-10
+
 * [CHANGE] [#907](https://github.com/k8ssandra/k8ssandra-operator/issues/907) Update to cass-operator v1.15.0, remove Vector sidecar, instead use cass-operator's server-system-logger Vector agent and only modify its config

Commit the changes:

git add CHANGELOG/CHANGELOG-${RELEASED_MAJOR_MINOR?}.md
git commit -m"Update changelog for v${RELEASED_FULL?}"

Check that the documentation builds

cd docs

npm install
npm run clean
npm run build:production

cd ..

If there are any errors, fix them and commit them on the release branch.

Create the release commit

Update the image tag in the default kustomization:

yq e -i '.images[0].newTag="v"+env(RELEASED_FULL)' config/deployments/default/kustomization.yaml

The diff should look like this:

@@ -8,5 +8,4 @@ resources:

 images:
   - name: k8ssandra/k8ssandra-operator
-    newTag: 1.6-latest
-
+    newTag: v1.6.1

Update the version in the release chart:

yq e -i '.version=env(RELEASED_FULL)' charts/k8ssandra-operator/Chart.yaml

The diff should look like this:

@@ -3,7 +3,7 @@ name: k8ssandra-operator
 description: |
   Kubernetes operator which handles the provisioning and management of K8ssandra clusters.
 type: application
-version: 1.6.1-SNAPSHOT
+version: 1.6.1
 dependencies:
   - name: k8ssandra-common
     version: 0.29.0

Commit:

git add config/deployments/default/kustomization.yaml charts/k8ssandra-operator/Chart.yaml
git commit -m"Release v${RELEASED_FULL?}"

Push the changes:

git push ${GIT_REMOTE?} release/${RELEASED_MAJOR_MINOR?}

Wait for the GitHub Actions workflows to complete.

Tag the release

git tag v${RELEASED_FULL?}
git push ${GIT_REMOTE?} v${RELEASED_FULL?}

Wait for the GitHub Actions workflows to complete.

Create the release in GitHub

Go to the New Release page.

click on “Choose a tag” and select the tag you just pushed, e.g. v1.6.1.
for the release title, use the name of the tag, e.g. “v1.6.1”.
for the description, just copy the contents for this version from the changelog.

Click on “Publish release”.

Prepare the branch for the next patch release

Update the image tag in the default kustomization:

yq e -i '.images[0].newTag=env(RELEASED_MAJOR_MINOR)+"-latest"' config/deployments/default/kustomization.yaml

The diff should look like this:

@@ -8,5 +8,4 @@ resources:

 images:
   - name: k8ssandra/k8ssandra-operator
-    newTag: v1.6.1
-
+    newTag: 1.6-latest

Update the version in the release chart:

yq e -i '.version=env(NEXT_FULL)+"-SNAPSHOT"' charts/k8ssandra-operator/Chart.yaml

The diff should look like this:

@@ -3,7 +3,7 @@ name: k8ssandra-operator
 description: |
   Kubernetes operator which handles the provisioning and management of K8ssandra clusters.
 type: application
-version: 1.6.1
+version: 1.6.2-SNAPSHOT
 dependencies:
   - name: k8ssandra-common
     version: 0.29.0

Commit the changes:

git add config/deployments/default/kustomization.yaml charts/k8ssandra-operator/Chart.yaml
git commit -m"Prepare next patch release"

Update the main branch

Merge with the “ours” strategy (none of the changes are applied):

git checkout main
git merge release/${RELEASED_MAJOR_MINOR?} -s ours

Then cherry-pick the changelog update, as well as any fixes you might have done on the branch (docs, failing tests, etc):

git cherry-pick -n <your commit SHA-1s...>

DO NOT cherry-pick the release contents that you cherry-picked in a previous step (they are already on main). DO NOT cherry-pick the “Release vx.x.x” or “Prepare next patch release” commits.

Amend the merge commit with your cherry-picks:

git add .
git commit --amend --no-edit

Push all the changes:

git push ${GIT_REMOTE?} main release/${RELEASED_MAJOR_MINOR?} --atomic

Feedback

Was this page helpful?

Glad to hear it! Please tell us how we can improve.

Sorry to hear that. Please tell us how we can improve.

Last modified September 18, 2024: Release v1.20.0 (9dc420a)