Release

Purpose

Release a new version of Kaniop using the release script and CI pipeline.

When to use

Use this skill when:

• The user asks to release a new version
• The user asks to cut a release or publish
• The user asks to tag a new version

Prerequisites

Before releasing, verify:

1. Working tree is clean — no uncommitted changes
2. You are on master — releases only happen from master
3. Local master is up to date with origin/master
4. No commits ahead of origin/master (output of git rev-list --count origin/master..HEAD must be 0)
5. Repository is not a shallow clone — git-cliff needs full history for accurate changelogs

Check with:

git status --short
git rev-parse --abbrev-ref HEAD
git pull origin master
git rev-list --count origin/master..HEAD
git tag --sort=-creatordate | head -3
git log --oneline v<latest_tag>..HEAD

Version Decision Guide

Use Semantic Versioning (MAJOR.MINOR.PATCH). Determine the bump type by analyzing commits since the last release.

Major Version (X.0.0)

Bump MAJOR when:

• Breaking changes to CRD specs
• Breaking changes to Helm chart values
• Breaking changes to operator behavior requiring manual intervention
• Commit message contains BREAKING CHANGE: or ! (e.g., feat!: ...)

Minor Version (0.X.0)

Bump MINOR when:

• New features added (feat: commits)
• New CRD types or fields
• New Helm chart configuration options
• Backward-compatible enhancements

Patch Version (0.0.X)

Bump PATCH when:

• Bug fixes (fix: commits)
• Documentation updates (docs: commits)
• Internal refactoring (refactor: commits)
• Dependency updates (chore(deps): commits)

Decision Process

1. Run: git log v<CURRENT_VERSION>..HEAD --oneline
2. Check commit messages for:
   • ! or BREAKING CHANGE: -> MAJOR
   • feat: -> MINOR
   • fix:, docs:, refactor:, etc. -> PATCH
3. If multiple types, use the highest precedence (MAJOR > MINOR > PATCH)

Release Process

Step 1: Verify Clean State

Ensure you're on master with no uncommitted changes, up to date with origin, and no commits ahead:

git checkout master
git pull origin master
git status  # Should show "nothing to commit, working tree clean"

Verify no commits ahead of origin/master:

git rev-list --count origin/master..HEAD  # Should output 0

Unshallow check — shallow clones produce incomplete changelogs:

git rev-parse --is-shallow-repository

If this outputs true, unshallow the repo before proceeding:

git fetch --unshallow origin
git fetch --tags origin

Step 2: Determine Version

1. Get current version:

   grep '^version =' Cargo.toml | head -1

2. Review commits since last release:

   git log v<CURRENT_VERSION>..HEAD --oneline

3. Decide on MAJOR, MINOR, or PATCH bump based on the Version Decision Guide above.

Step 3: Create Release Branch

git checkout -b release/v<NEW_VERSION>

Step 4: Update Version

Edit the root Cargo.toml and update the version in the [workspace.package] section:

version = "<NEW_VERSION>"

Then propagate the version across all workspace files:

make update-version

This automatically updates:

• All workspace dependency versions in root Cargo.toml
• Cargo.lock
• charts/kaniop/Chart.yaml (version, appVersion, image tags, annotations)
• Artifact Hub changes annotation (via git-cliff with .ci/cliff-chart.toml)

Important: After running make update-version, verify the artifacthub.io/changes annotation in charts/kaniop/Chart.yaml includes any chart-scoped commits (e.g., feat(chart):, fix(chart):). If it shows "No changes in the chart" but chart commits exist, see Troubleshooting.

Step 5: Update Changelog

Generate the changelog using git-cliff:

make update-changelog

This runs: git cliff -t v<VERSION> -u -p CHANGELOG.md

The changelog is generated from conventional commits and grouped by type (Added, Fixed, Documentation, Build, Refactor, Styling, Testing, Chore). Release commits are excluded.

Step 6: Regenerate Examples

If CRD fields were changed in this release cycle:

make examples

Step 7: Commit Changes

Stage and commit all changes:

git add .
VERSION=$(sed -n 's/^version = "\(.*\)"/\1/p' Cargo.toml | head -n1)
git commit -m "release: Version $VERSION"

Step 8: Push Branch and Create PR

git push -u origin release/v<NEW_VERSION>

Create a pull request to merge into master.

Step 9: After Merge

After the PR is merged to master, tagging and releasing is done automatically by CI:

1. auto-tag.yml reads the new version from CHANGELOG.md
2. Creates a signed GPG tag v<VERSION>
3. Pushes the tag to GitHub

The tag then triggers:

• docker_images.yml: Builds/pushes multi-arch Docker images (amd64, arm64), creates GitHub Release
• rust.yml: Publishes crates to crates.io
• helm.yml: Publishes signed Helm chart to GHCR OCI registry

Monitor with:

gh run list --limit 5

Note: Do not manually create tags — CI handles this automatically.

What NOT to Do