Version Management Workflow

Version Management Workflow

The Krill platform uses an automated version management system that ensures version consistency across all components of the project. This document explains how the version bumping workflow operates.

Overview

The version management workflow is defined in .github/workflows/Release Version.yml and serves as the single source of truth for version bumping across the entire Krill ecosystem.

Version Source of Truth

The master version is stored in version.txt at the root of the repository in the format:

MAJOR.MINOR.PATCH

Example: 1.0.345

Workflow Trigger

The workflow is manually triggered via GitHub Actions:

on:
  workflow_dispatch:

Version Bump Process

The workflow performs the following steps:

1. Read and Bump Version

The workflow reads the current version from version.txt, increments the patch version, and also increments the Android versionCode:

graph LR
    A[Read version.txt] --> B[Parse MAJOR.MINOR.PATCH]
    B --> C[Increment PATCH]
    C --> D[Write new version]
    A --> E[Read Android versionCode]
    E --> F[Increment versionCode]
    F --> G[Update 5 version files]
    G --> H[Commit version files]
    H --> I[Update version.html]
    I --> J[Commit documentation]
    J --> K[Create git tag]

2. Update All Version Files

After bumping the version, the workflow updates all files that reference the version number:

File	Field Updated	Purpose
version.txt	Full version string	Source of truth
server/build.gradle.kts	version = "X.X.X"	Server build version
composeApp/build.gradle.kts	packageVersion = "X.X.X"	Desktop app package version
androidApp/build.gradle.kts	versionName = "X.X.X"	Android app version name
androidApp/build.gradle.kts	versionCode = NNN	Android app version code
server/package/DEBIAN/control	Version: X.X.X	Debian package version

3. Commit Version Changes

Version file changes are committed to the main branch:

git add version.txt
git add server/build.gradle.kts
git add composeApp/build.gradle.kts
git add androidApp/build.gradle.kts
git add server/package/DEBIAN/control
git commit -m "Bump version to X.X.X"
git push

4. Update Documentation

The workflow updates the version documentation file at docs/_includes/version.html with the new version and release date:

<p>
Current Version: <strong>X.X.X</strong>
    <br />
Released: Month DD, YYYY
</p>

5. Commit Documentation

Documentation changes are committed separately:

git add docs/_includes/version.html
git commit -m "Update version documentation for release X.X.X"
git push

6. Create Git Tag

A git tag is created and pushed for the new version:

git tag -a "vX.X.X" -m "Release version X.X.X"
git push origin "vX.X.X"

Version File Update Details

Server Build (server/build.gradle.kts)

version = "1.0.345"

Desktop Package (composeApp/build.gradle.kts)

packageVersion = "1.0.345"

Android App (androidApp/build.gradle.kts)

versionCode = 148
versionName = "1.0.345"

Debian Package (server/package/DEBIAN/control)

Version: 1.0.345

Usage

To bump the version and update all files:

1. Navigate to Actions tab in GitHub
2. Select Release Version.yml workflow
3. Click Run workflow
4. Click the green Run workflow button

The workflow will:

• ✅ Bump the patch version in version.txt
• ✅ Update all gradle build files
• ✅ Update the Debian control file
• ✅ Commit version bump changes
• ✅ Update version documentation (version.html)
• ✅ Commit documentation changes
• ✅ Create a git tag with the new version
• ✅ Push all changes to main

Integration with Release Workflow

This version management workflow is designed to work in tandem with the “Release The Kraken.yml” workflow. The typical release process is:

graph TD
    A[Run Release Version.yml] --> B[Version bumped & tagged]
    B --> C[Run Release The Kraken.yml]
    C --> D[Build artifacts with new version]
    D --> E[Deploy to repositories]
    E --> F[Create GitHub Release]

The “Release The Kraken.yml” workflow picks up the version from the already-updated files and uses it for building and packaging artifacts.

Benefits

• Single Source of Truth: All versions come from version.txt
• Consistency: All components use the same version number
• Automation: No manual editing of version numbers
• Traceability: Git tags provide clear version history
• Documentation: Automatic update of version documentation

Version Numbering Scheme

Krill follows semantic versioning with the format MAJOR.MINOR.PATCH:

• MAJOR: Incompatible API changes
• MINOR: New functionality in a backward-compatible manner
• PATCH: Backward-compatible bug fixes (auto-incremented)

The Android versionCode is a monotonically increasing integer used by the Play Store to determine which version is newer.

Troubleshooting

If the workflow fails:

1. Check that all files exist in their expected locations
2. Verify that the GitHub Actions bot has write permissions
3. Ensure there are no merge conflicts on the main branch
4. Review the workflow logs for specific error messages

Future Enhancements

Potential improvements to the version management system:

• Support for major/minor version bumps
• Automated changelog generation
• Version bump based on commit messages (conventional commits)
• Pre-release version support (alpha, beta, rc)