RELEASE_PROCEDURE.md

KSML Release Procedure

Overview

• main branch: Development branch for new features
• release/<major>.<minor>.x branches: Used for releases and patches
• All releases are built from release branches
• Changelog is maintained through GitHub Releases
• For major/minor releases: RC versions and the actual release are created on main, then release branch is created from the final release tag

Complete Release Process

Step 1: Prepare Release Candidates (Major/Minor Releases Only)

For major/minor releases (e.g., 1.1.0, 2.0.0):

1. Ensure all features are merged to main
2. Set RC version in main branch:

   mvn versions:set -DgenerateBackupPoms=false
   # Enter version like: 1.1.0-RC1

3. Run mvn clean package -DskipTests -P '!sonarqube' to update NOTICE.txt files
4. Build, test, commit with message Release 1.1.0-RC1
5. Tag: git tag 1.1.0-RC1 -m "Release 1.1.0-RC1" -a
6. Push tag and test RC git push origin 1.1.0-RC1. For example by running e2e tests in Staging Cloud.
7. Create additional RCs (RC2, RC3) as needed
8. Go to GitHub -> Releases -> "Draft new release" -> "Generate release notes" -> uncheck "latest release" -> check "pre-release"-> OK
9. Test the RC1 image from Harbor(for example in e2e tests in Staging Cloud)

Step 2: Release Major/Minor Version (Major/Minor Releases Only)

Still on main branch:

1. Set the release version:

   mvn versions:set -DgenerateBackupPoms=false
   # Enter version like: 1.1.0

2. Update NOTICE.txt files:

   mvn clean package -DskipTests -P '!sonarqube'

3. Build Docker Image Locally:

   Run the automated build script:

   ./build-local-docker.sh

   This script will:

   • Build the project with Maven (including all tests)
   • Prepare build artifacts in build-output/
   • Build Docker image using the main Dockerfile
   • Create image tagged as axual/ksml:local

4. Test the Release:

   • Modify run.sh and docker-compose.yml to use axual/ksml:local
   • Start environment: docker compose up -d
   • Verify data generator: docker compose logs example-producer -f
   • Execute ./examples/run.sh and verify:
     • Correct version appears: Starting KSML Runner x.x.x (2025-...)
     • Wait ~2 minutes for examples to run without errors
     • Stop the script after verification

5. Update docs/release-notes.md:

   • Add the new version entry (e.g. ## 1.1.0 (YYYY-MM-DD)) at the top of the list
   • Add the version to the table of contents
   • Summarize the key changes

6. Commit changes:

   git add **/pom.xml **/NOTICE.txt docs/release-notes.md
   git commit -m "Release 1.1.0"

7. Create and push tag:

   git tag 1.1.0 -m "Release 1.1.0" -a
   git push origin 1.1.0

Step 3: Create Release Branch and Update GitHub Actions (Major/Minor Releases Only)

After the release tag is created on main:

1. Create release branch from release tag:

   git checkout -b release/1.1.x 1.1.0

   Important: The release branch is created from the final release tag (e.g., 1.1.0), not from any RC tag. This ensures the release branch contains all fixes and changes made during the RC process.

2. Update GitHub Actions on the release branch:

   a. Update .github/workflows/build-push-docker.yml:

   • Change Docker tags from snapshot to <major>.<minor>-snapshot
   • Update helm-chart-release job: app-version: <major>.<minor>-snapshot, version: <major>.<minor>.0-snapshot

   b. Update .github/workflows/package-push-helm.yml:

   • Change default version parameter to <major>.<minor>.0-snapshot in both workflow_dispatch and workflow_call

   c. Update .github/workflows/release-push-docker.yml:

   • Add <major>.<minor> tag to all Docker registries (axual/ksml, ghcr.io, registry.axual.io)

3. Commit and push the release branch:

   git add .github/workflows/*.yml
   git commit -m "Update GitHub Actions for release/<major>.<minor>.x branch"
   git push origin release/<major>.<minor>.x

Step 4: Create GitHub Release

1. Go to GitHub -> Releases -> "Draft new release"
2. Select the new tag (e.g., 1.1.0)
3. Set previous tag for comparison (e.g., 1.0.8)
4. Click "Generate release notes"
5. Structure the release notes:
   • "What's Changed": Write concise summary of key changes
   • "Full Changelog": Keep auto-generated commit list
6. Publish the release
7. Upload ksml-language-spec.json

Step 5: Monitor Build

1. Go to GitHub -> Actions -> Monitor release workflow
2. Ensure the build completes successfully

Step 6: Verify Release Artifacts

After the build completes, verify the Docker image and Helm chart are published:

# Check Docker image tags
skopeo list-tags docker://registry.axual.io/opensource/images/axual/ksml

# Inspect the specific release image
skopeo inspect --override-os linux docker://registry.axual.io/opensource/images/axual/ksml:1.1.0

# Check Helm chart tags
skopeo list-tags docker://registry.axual.io/opensource/charts/ksml

Step 7: Set Next Development Version

1. In release branch:

   git checkout release/1.1.x
   mvn versions:set -DgenerateBackupPoms=false
   # Enter next patch snapshot: 1.1.1-SNAPSHOT
   mvn clean package -DskipTests # To generate NOTICE.TXT

   Update packaging/helm-charts/ksml/Chart.yaml version and appVersion, i.e. "version: 1.1.1-SNAPSHOT" and "appVersion: "1.1.1-snapshot"" Add: git add **/pom.xml **/NOTICE.txt **/Chart.yaml Commit: git commit -m "Prepare for next development iteration" Push: git push origin release/1.1.x

2. In main branch:

   git checkout main
   mvn versions:set -DgenerateBackupPoms=false
   # Enter next minor/major snapshot: 1.2.0-SNAPSHOT
   mvn clean package -DskipTests # To generate NOTICE.TXT

   Update packaging/helm-charts/ksml/Chart.yaml version and appVersion, i.e. "version: 1.2.0-SNAPSHOT" and "appVersion: "1.2.0-snapshot"" Add: git add **/pom.xml **/NOTICE.txt **/Chart.yaml Commit: git commit -m "Prepare for next development iteration" Push: git push origin main

Patch Release Process

When doing a patch release (e.g., 1.0.9, 1.1.1):

Note: GitHub Actions do not need to be updated for patch releases as they already contain the correct snapshot versions for the release branch.

Step 1: Prepare Patch

1. Checkout existing release branch:

   git checkout release/1.0.x

2. Apply fixes by either:

   • Cherry-picking from main: git cherry-pick <commit-hash>
   • Creating fixes directly in release branch

Step 2: Set Release Version

1. Set Maven version:

   mvn versions:set -DgenerateBackupPoms=false
   # Enter version like: 1.0.9

2. Update packaging/helm-charts/ksml/Chart.yaml version and appVersion to the release version, i.e. version: 1.0.9 and appVersion: "1.0.9"

Step 3: Build and Update Files

1. Update NOTICE.txt files:

   mvn clean package -DskipTests

Step 4: Build Docker Image Locally

Run the automated build script:

./build-local-docker.sh

This script will:

• Build the project with Maven (including all tests)
• Prepare build artifacts in build-output/
• Build Docker image using the main Dockerfile
• Create image tagged as axual/ksml:local

Step 5: Test the Release

• Modify run.sh and docker-compose.yml to use axual/ksml:local
• Start environment: docker compose up -d
• Verify data generator: docker compose logs example-producer -f
• Execute ./run.sh and verify:
  • Correct version appears: Starting KSML Runner x.x.x (2025-...)
  • Wait ~2 minutes for examples to run without errors
  • Stop the script after verification

Step 6: Update Release Notes

Update docs/release-notes.md:

• Add the new version entry (e.g. ## 1.0.9 (YYYY-MM-DD)) at the top of the list
• Add the version to the table of contents
• Summarize the key changes

Step 7: Commit Changes

git add **/pom.xml **/NOTICE.txt packaging/helm-charts/ksml/Chart.yaml docs/release-notes.md
git commit -m "Release 1.0.9"

Step 8: Create and Push Tag

git tag 1.0.9 -m "Release 1.0.9" -a
git push origin 1.0.9

Step 9: Create GitHub Release

1. Go to GitHub -> Releases -> "Draft new release"
2. Select the new tag (e.g., 1.0.9)
3. Set previous tag for comparison (e.g., 1.0.8)
4. Click "Generate release notes"
5. Structure the release notes:
   • "What's Changed": Write concise summary of key changes
   • "Full Changelog": Keep auto-generated commit list
6. Publish the release
7. Upload ksml-language-spec.json

Step 10: Monitor Build and Push Branch

1. Go to GitHub -> Actions -> Monitor release workflow
2. Only after successful build, push the branch:

   git push origin release/1.0.x

Step 11: Verify Release Artifacts

After the build completes, verify the Docker image and Helm chart are published:

# Check Docker image tags
skopeo list-tags docker://registry.axual.io/opensource/images/axual/ksml

# Inspect the specific release image
skopeo inspect --override-os linux docker://registry.axual.io/opensource/images/axual/ksml:1.0.9

# Check Helm chart tags
skopeo list-tags docker://registry.axual.io/opensource/charts/ksml

Step 12: Set Next Development Version

1. Switch to main branch:

   git checkout main

2. Set the next patch snapshot version:

   mvn versions:set -DgenerateBackupPoms=false
   # Enter next patch snapshot, e.g.: 1.0.10-SNAPSHOT

3. Update NOTICE.txt files:

   mvn clean package -DskipTests

4. Update packaging/helm-charts/ksml/Chart.yaml:

   • Set version: 1.0.10-SNAPSHOT
   • Set appVersion: "1.0.10-snapshot"

5. Commit and push to main:

   git add **/pom.xml **/NOTICE.txt packaging/helm-charts/ksml/Chart.yaml
   git commit -m "Prepare for next development iteration"
   git push origin main

Version Numbering

• Major: Breaking changes
• Minor: New features (backward compatible)
• Patch: Bug fixes
• Snapshot: Development versions (-SNAPSHOT)
• RC: Release candidates (-RC<number>)

Helm Chart and Docker Image Versioning

Important: The Helm Chart version and appVersion are always aligned with the Docker image tag:

• Released versions: Both set to the same version (e.g., 1.1.1)

  • Helm chart version: 1.1.1
  • Helm chart appVersion: 1.1.1
  • Docker image tag: axual/ksml:1.1.1

• Snapshot builds:

  • Main branch: 0.0.0-snapshot for both
  • Release branches: <major>.<minor>.<patch>-snapshot for both

The CI/CD pipeline enforces this alignment by overriding Chart.yaml values during helm package execution. The Chart.yaml file in the repository serves as a template and its values are replaced during builds.

Rollback Procedure

If issues found after tagging but before release build:

1. Delete remote tag: git push origin :refs/tags/<version>
2. Delete local tag: git tag -d <version>
3. Fix issues and restart from appropriate step