Routine Versioning

Author: Drew Shea, Created: 2025-11-16

Routine Versioning enables multiple versions of the same Routine to coexist in Xperiflow. This supports evolution, backward compatibility, and controlled updates.

Info: Routine versioning follows semantic versioning (Major.Minor.Patch), similar to software libraries like NumPy or pandas.

---

Overview

Routine versioning lets you:

• Track Changes: See how Routines evolve over time
• Maintain Compatibility: Keep older versions available while introducing new ones
• Control Updates: Choose when to adopt new versions
• Preserve Stability: Existing Routine Instances continue using their original version

Each Routine defines a version in its metadata. The system stores multiple versions and can retrieve the latest or a specific version.

As seen in the image above, SensibleAI Studio manages all prior versions of a given Routine and allows the user the ability to specify which version to make use of.

---

Core Concepts

Semantic Versioning

Routines use Semantic Versioning with three components:

Version Format:

• Major Version: Breaking changes that may not be compatible with previous versions
• Minor Version: New features or enhancements that remain backward compatible
• Patch Version: Bug fixes and small improvements that maintain compatibility

Example Versions:

• 0.x.x: Beta release
• 1.0.0: Initial release
• 1.x.0: Added new features (minor update)
• 1.1.x: Fixed bugs (patch update)
• 2.0.0: Major changes that may break compatibility

Version Storage

The system stores all versions of a Routine:

How Versions Are Organized:

• Routines are indexed by name
• Each name maps to a collection of versions
• Versions are stored with their full implementation
• The system can retrieve any version by name and version number

Version Registry:

• When a Routine is registered, it's added to the version registry
• Multiple versions of the same Routine can exist simultaneously
• Versions are sorted chronologically (oldest to newest)
• The latest version is automatically identified

Version Access

You can create Routine Instances in relation to Versions in two ways:

By Name Only (UI only):

• Returns the latest version
• Useful when you want the most current implementation
• Automatically uses the highest version number

By Name and Version (Required by XBR C# SDK):

• Returns a specific version
• Ensures consistent behavior across executions

You will notice within the XBR C# SDK that it requires you to provide the routineTypeName and the Routine routineVersion in order to force you to be aware and explicit on the version of the Routine that intend to make use of.

Version as String:

// Get the routine client
var routineClient = XBRApi.Routines.GetRoutineClient(sessionInfo, projectId);

// Create instance with explicit version as string
// This ensures you get exactly version 1.2.3, not whatever is "latest"
var instance = routineClient.CreateRoutineInstanceAsync(
    routineTypename: "LinearRegression",
    routineVersion: "1.2.3",
    name: "Sales Forecasting Model",
    description: "Production model using stable v1.2.3"
).Result;

// This will always use version 1.2.3, even if v1.2.4 or v2.0.0 is released later

The C# SDK's requirement for explicit versioning is a deliberate design decision to ensure stability and predictability in production environments, whereas UI users may prefer the convenience of automatically getting the latest version for exploratory or development work.

---

Routine Instance Versioning

Instance-Version Association

When you create a Routine Instance, it's associated with a specific Routine version:

Version Assignment:

• Once assigned, the Instance's version doesn't change automatically

Version Persistence:

• The Routine Instance stores its version in the database
• The version is part of the Instance's metadata
• The Instance always uses the same version throughout its lifetime

Version Stability

Routine Instances maintain their version for stability:

Why Versions Don't Auto-Update:

• Predictability: Instances behave consistently over time
• Compatibility: Avoids breaking changes from version updates
• Control: You decide when to upgrade

Version Locking:

• An Instance created with version 1.0.0 continues using 1.0.0
• Even if version 2.0.0 becomes available, the Instance doesn't upgrade
• This prevents unexpected behavior changes

---

Version Lifecycle

Creating New Versions

When a Routine is updated, a new version is created:

Version Creation Process:

1. Development: The Routine is modified with new features or fixes
2. Version Assignment: A new version number is assigned (e.g., 1.1.0)
3. Registration: The new version is registered in the system
4. Availability: The new version becomes available for use

Version Coexistence:

• Old versions remain available
• New versions are added alongside old ones
• All versions can be accessed independently

Version Discovery

The system helps you discover available versions:

Version Listing:

• You can query all versions of a Routine
• Versions are returned in chronological order (oldest first)
• Each version includes its metadata (author, creation date, description)

Version Comparison:

• You can compare different versions
• Documentation shows what changed between versions
• This helps decide whether to upgrade

---

Version Compatibility

Backward Compatibility

Understanding compatibility helps with version selection:

Minor and Patch Versions:

• Generally backward compatible
• New features added without breaking existing functionality
• Safe to upgrade in most cases

Major Versions:

• May include breaking changes
• May require parameter changes or workflow updates
• Review changes before upgrading

Version Migration

Warning: As of Xperiflow release v4.1.0, migrating a Routine Instance to a new version is considered a “manual” process. That is why we will keep around old versions of Routines for as long as possible. We plan to introduce “opt-in” Routine Instance version upgrades for OneStream Certified Routines (not community Routines).

When upgrading to a new version:

Migration Considerations:

• Parameter Changes: New versions may require different parameters
• Method Changes: Methods may have different signatures or behaviors
• Artifact Changes: Output formats may change
• State Compatibility: Stateful Routines may need state migration

Migration Strategy:

• Review version release notes and documentation
• Test new versions in non-production environments
• Create new Instances with new versions for testing
• Migrate existing Instances only after validation

---

Version Management

Version Tracking

The system tracks version information:

Version Metadata:

• Version Number: The semantic version (e.g., 1.2.3)
• Creation Date: When the version was created
• Author: Who created the version
• Description: What changed in this version

Version History:

• All versions are preserved in the system
• You can view the complete version history
• Historical versions remain accessible

Version Documentation

Each version includes documentation:

Version-Specific Documentation:

• Describes features available in that version
• Lists methods and parameters for that version
• Explains changes from previous versions

Documentation Access:

• Documentation is available for all versions
• You can view documentation for any specific version
• This helps understand what each version provides

---

Best Practices

Version Selection

Choose versions thoughtfully:

For New Instances:

• Use the latest version unless you have specific requirements
• Review release notes before creating Instances
• Test new versions before production use

For Existing Instances:

• Create new Instances to test new versions
• Upgrade only after thorough testing

Revisit Routine Documentation Occasionally

It is possible (however, incredibly unlikely) that we may have to deprecate an old Routines due to security, python environment, package compatibility.

info

**Note:** We plan to embed a deprecation notice directly in SensibleAI Studio in the future for any live Routine Instances you are using that are marked for deprecation.

Change Documentation:

• Be on the lookout for old Routine version deprecation.