Skip to content

Versioning Philosophy

Jump to bottom
Bobby Comet edited this page Sep 8, 2026 · 1 revision

Kalium Versioning Philosophy

Kalium uses a milestone-based versioning approach rather than a strict interpretation of semantic versioning.

Version numbers are based on changes to user workflows, environment capabilities, compatibility, and architecture, not simply the number of files changed, commits made, or the size of an internal refactor.

The goal is to make Kalium versions communicate meaningful changes to how users create, configure, maintain, repair, and migrate modding environments.

Version Structure

Kalium follows a four-part milestone versioning scheme:

MAJOR.MINOR.FEATURE.PATCH

Example:

1.1.1.1xx
│ │ │ └── Patch / maintenance release
│ │ └──── Feature expansion within the current workflow
│ └────── Environment-management milestone
└──────── Major architectural generation

Each component represents a different level of user-visible change:

  • MAJOR — Fundamental architectural or environment-management generation changes.
  • MINOR — Significant workflow milestones and major application evolution while preserving the overall Kalium model.
  • FEATURE — New capabilities, integrations, compatibility improvements, environment tools, and other meaningful expansions.
  • PATCH — Bug fixes, reliability improvements, diagnostics corrections, packaging fixes, documentation updates, and other maintenance releases.

Kalium's versioning communicates how the environment-management experience evolves rather than measuring development effort.

Major Versions (X.0.0.0)

A major version represents a fundamental shift in what Kalium is or how it manages modding environments.

A major release is reserved for changes that significantly alter:

  • Kalium's core architecture
  • The environment-management model
  • MO2 instance compatibility
  • The meaning of a Kalium-managed environment
  • How users create, maintain, or recover environments
  • Core configuration or integration systems
  • Project or instance data in a way that breaks compatibility

Examples:

Would require a major version

  • Replacing the current environment-management architecture
  • Introducing a fundamentally different MO2 integration model
  • Replacing the current Proton/Wine configuration system
  • A new instance format that breaks compatibility
  • Replacing the current Steam integration architecture
  • A fundamentally different environment or migration system

A major version is not based on code size.

A large internal rewrite does not automatically require a major version if existing environments and user workflows continue to function normally.

Minor Versions (X.Y.0.0)

Minor versions represent significant milestones in Kalium's evolution while preserving its overall identity and maintaining compatibility where practical.

These releases may introduce substantial improvements across multiple systems without fundamentally changing Kalium's purpose.

Examples may include:

  • A major redesign of the setup workflow
  • A significant expansion of environment management
  • A new instance-management system
  • A major migration or recovery workflow
  • Significant improvements spanning Steam, Proton, Wine, MO2, and supporting tools
  • Major improvements to diagnostics and repair
  • Broad compatibility improvements across supported environments

Minor versions should generally preserve existing Kalium-managed environments unless a documented migration is required.

Feature Versions (X.Y.Z.0)

Feature versions represent meaningful expansion of Kalium while keeping the existing environment-management workflow intact.

These releases add capabilities, integrations, tools, or compatibility improvements without fundamentally changing what Kalium is.

Examples:

  • New game support
  • New Proton compatibility improvements
  • New supporting-tool integration
  • New MO2 plugin installation capabilities
  • New diagnostics
  • New repair operations
  • New migration capabilities
  • New Steam library handling
  • New CLI commands
  • New configuration controls
  • New backpatching support
  • New GOG or Heroic functionality

A Feature release can be substantial.

The defining characteristic is that Kalium's existing workflow remains recognizable while gaining new capabilities.

Patch Versions (X.Y.Z.P)

Patch releases focus on correctness, stability, reliability, and refinement.

They include:

  • Bug fixes
  • Setup corrections
  • Proton/Wine configuration fixes
  • NXM registration fixes
  • Steam integration fixes
  • MO2 configuration corrections
  • USVFS configuration fixes
  • Diagnostics corrections
  • UI fixes
  • Packaging fixes
  • Performance improvements
  • Documentation corrections
  • Compatibility fixes that do not introduce a new workflow

Patch releases should not fundamentally change how users manage their environments.

Internal Changes vs Environment Workflow Changes

Not every large engineering change requires a version increase.

Kalium distinguishes between:

Internal Improvements

Large engineering changes that improve implementation while preserving the user's existing workflow.

Examples:

  • Refactoring environment configuration code
  • Reworking internal Steam detection
  • Improving Proton discovery
  • Replacing internal configuration algorithms
  • Cleaning up prefix management
  • Improving error handling
  • Removing duplicate systems
  • Rewriting diagnostic internals

These may remain within the current version line when the user-facing workflow remains substantially unchanged.

Workflow Changes

Changes that alter what users can do or how they manage their environments.

Examples:

  • A new MO2 setup workflow
  • A new migration workflow
  • A new environment recovery system
  • A new instance-management model
  • A new supporting-tool integration workflow
  • A new game binding system
  • A new compatibility-management system

These may require a Feature, Minor, or Major version increase depending on their scope and impact.

Example: Environment Configuration Improvements

Suppose Kalium substantially improves:

  • Proton detection
  • Wine prefix configuration
  • USVFS setup
  • MO2 INI configuration
  • Steam shortcut generation

If the user still performs the same basic workflow:

Select MO2
      ↓
Select Game
      ↓
Select Proton
      ↓
Kalium Configures Environment
      ↓
Launch MO2

then the changes may remain within the existing version line.

The implementation may have changed significantly, but the environment-management workflow has not fundamentally changed.

Example: New Repair Workflow

Suppose Kalium introduces a comprehensive repair system capable of:

  • Detecting broken prefixes
  • Rebuilding environment configuration
  • Re-registering NXM
  • Repairing Steam integration
  • Reconfiguring USVFS
  • Restoring required MO2 settings

This is more than a collection of bug fixes if it introduces a new user workflow:

Diagnose Environment
        ↓
Identify Problem
        ↓
Repair Environment
        ↓
Verify Configuration

Depending on its scope, that could justify a Feature or Minor release.

Example: Future Environment Transformation

A future Kalium release could potentially introduce an entirely new environment model capable of:

  • Managing multiple isolated environments as first-class objects
  • Automatically migrating environments between Proton generations
  • Reconstructing environments from portable environment definitions
  • Synchronizing environment configuration independently from MO2 installations
  • Providing a fundamentally different lifecycle for modding environments

If that system fundamentally changes what a Kalium-managed environment means, it could justify a Major version.

The deciding factor is not how much code was written.

The deciding factor is whether the environment-management model itself changed.

Compatibility Matters

Kalium operates around software with its own compatibility boundaries, including:

  • Steam
  • Proton
  • Wine
  • MO2
  • USVFS
  • LOOT
  • Supporting tools
  • Individual games

Therefore, version decisions should consider environment compatibility as well as application functionality.

A change that significantly affects existing Kalium-managed environments may warrant a larger version increment even if the underlying implementation is relatively small.

Conversely, an extensive internal change that preserves existing environments may remain a smaller release.

The Rule

Before increasing the version number, ask:

"Does this change what Kalium is, or does it improve what Kalium already does?"

If it improves the existing experience:

  • Bug fixes and maintenance → Patch
  • New capabilities and integrations → Feature
  • Significant environment-management milestones → Minor

If it changes Kalium's identity, architecture, or fundamental environment-management model:

  • Major version

Philosophy

Kalium versions are about user-visible evolution of the modding environment, not development effort.

A one-line change that fundamentally alters environment compatibility may deserve a major version.

A thousand-line rewrite of the Proton configuration system may not.

The purpose of versioning is to communicate the significance of a release to users, not to measure how difficult it was for the developer to build.

Kalium evolves around a simple principle:

The version number should tell users how much their modding environment experience has changed.

Clone this wiki locally