Release Management

Overview

Release management is a tool in KOS Studio that allows users to create a manufacturing release from a release template. While the template defines which images comprise the release and where they are placed in the boot queue, the release manager tool allows users to build versioned release candidates from the template. Users first create a new release version of a template, then create a release candidate. The release candidate will include the latest build of each image defined in the template, resulting in a single disk image that can be installed onto a device in manufacturing. As testing proceeds on the release candidate, individual images in a release candidate can be marked verified, making them immutable for future release candidates. Once all images in the release candidate have been verified, the final disk image can be released to manufacturing. Releases are immutable and can be regenerated at any time in the future, even if the underlying KABs are removed from the market or local artifact stores. This also ensures that any previously release can be recreated and installed in the future for testing purposes.

This tool is available to all users in KOS Studio (not just administrators), making it easy for development teams to manage releases collaboratively while maintaining control and consistency through the template system.

Understanding the Release Workflow

Before using the Release Manager, it’s helpful to understand how the release process works in KOS.

The Three-Tier Release Structure

KOS uses a hierarchical structure for managing releases:

  1. Release Templates (Created in Release Manager – Templates)
    Templates define the standard configuration: which images to deploy, in what order, and with what authority. Templates are created and managed by administrators.
  2. Release Versions (Managed in Release Manager)
    Versions represent specific iterations of a template. For example, you might have versions like “v1.0”, “v2.0”, or “2025-Q1”. Each version can have multiple release candidates.
  3. Release Candidates (Managed in Release Manager)
    Candidates are specific instances that can be built into deployable images. A version might have multiple candidates as you refine and test before final release. Once you have verified the images in the release candidate ensuring they work as expected. These images remain immutable for other release candidates helping teams working iteratively to get the final release candidate out of the door.

Why This Structure?

Templates provide consistency:
The base configuration is defined once and reused across versions.

Versions provide organization:
Different releases are clearly separated and can be managed independently.

Candidates provide iteration:
Multiple attempts can be made within a version until the release is ready for deployment.

From Template to Deployed Image

The complete flow is:

  1. Administrator creates a Release Template defining the configuration
  2. User creates a Release Version based on that template
  3. User creates a Release Candidate within that version
  4. User builds an image from the release candidate
  5. The built image can be deployed to devices

Accessing Release Manager

Opening the Tool

  1. Log into KOS Studio (as any user, not just administrators)
  2. In the upper-right corner, click Tools
  3. Select Release Manager from the menu

The Release Manager window opens, displaying the release management interface.

Understanding the Release Manager Interface

The Release Manager interface is organized into three main sections:

Release Templates Panel (Left – Top)

Displays all available release templates from your current project:

  • Only shows templates that are not hidden
  • Templates created in Release Manager – Templates appear here automatically
  • Locked templates are usable but cannot be modified
  • Select a template to begin working with versions

Release Versions Panel (Center)

Shows all versions created for the selected template:

  • Lists versions alphabetically or chronologically
  • Each version can be expanded to show details
  • Versions can be created, edited, locked, or deleted
  • Select a version to work with release candidates

Release Candidates Panel (Left- Bottom)

Displays all candidates for the selected version:

  • Shows candidate details and status
  • Candidates can be created, edited, or deleted
  • Build action is available for each candidate
  • Shows build progress and results

Getting Started: Empty States

No Templates Available

When you first access Release Manager and no templates exist:

For Administrators:

  • Message indicates no templates are available
  • Guided to create a template in Release Manager – Templates
  • Direct link or button to open Release Manager – Templates

For Non-Administrators:

  • Message indicates no templates are available
  • Informed that administrators must create templates
  • No option to create templates (must be done by admins in Release Manager – Templates)

Template with No Versions

When you select a template that has no versions yet:

  • Message indicates no versions are available for this template
  • “Create new version” button is prominently displayed
  • Instructions guide you to create your first version

Version with No Candidates

When you select a version that has no candidates yet:

  • Message indicates no release candidates are available for this version
  • “Create new candidate” button is prominently displayed
  • Instructions guide you to create your first release candidate

Creating Release Versions

Starting a New Version

To create a version for a release template:

  1. Select a template from the Release Templates panel
  2. Click Create new version (or the “+” button)
  3. In the “Create new version” dialog, enter:
    • Version Name (required) – Must be unique within this template
    • Description (optional) – Explain what’s in this version
  4. Click Create

What happens next:

  • The new version appears in the Release Versions panel
  • The version is automatically selected
  • The version is appended under its template in the list
  • The Release Candidates panel shows the empty state for this version
  • You’re prompted to create your first release candidate

Duplicate Prevention:
You cannot create two versions with the same name for a release template. Choose unique, descriptive version names like “v1.0”, “v2.0”, or “2025-Q1”.

Version Naming Best Practices

Use clear, meaningful version names:

  • Semantic versioning: “v1.0.0”, “v2.1.0”
  • Date-based: “2025-Q1”, “2025-01-Release”
  • Descriptive: “Beta-Testing”, “Production-January”
  • Milestone-based: “Phase1”, “Launch-Candidate”

Managing Release Versions

Viewing Version Details

When you select a version from the list, you see:

  • Version name
  • Description
  • Lock status
  • Creation date and creator information
  • List of all release candidates for this version

Editing Release Versions

To modify an existing version:

  1. Select the version from the Release Versions panel
  2. Click Edit (or the edit icon)
  3. In the edit dialog, you can modify:
    • Version Name (must remain unique)
    • Description
    • Lock state (toggle locked/unlocked)
  4. Click Save

What happens:

  • Changes appear immediately in the Release Manager
  • Other users see the updated information instantly
  • Locked status affects what operations are allowed

Version Lock State

Locking a Version:
When you lock a version:

  • You cannot create new release candidates for this version
  • You cannot delete this version
  • You cannot edit version information (unless you unlock it first)
  • Existing candidates can still be built
  • This protects stable versions from accidental changes

Unlocking a Version:
When you unlock a version:

  • You can create new release candidates
  • You can delete the version if needed
  • You can edit version information
  • Full management capabilities are restored

When to lock versions:

  • After finalizing a production release
  • When maintaining stable milestone versions
  • To prevent accidental modifications to tested configurations

Deleting Release Versions

To remove a version:

  1. Select the version from the Release Versions panel
  2. Click Delete (or the delete icon)
  3. In the confirmation dialog, type the version name exactly
  4. Click Confirm to complete deletion

Important:

  • You cannot delete locked versions (unlock them first)
  • Deletion is permanent and removes all associated release candidates
  • The version disappears for all users immediately
  • Consider locking and hiding old versions instead of deleting them

Creating Release Candidates

Starting a New Candidate

To create a release candidate for a version:

  1. Select a template from the Release Templates panel
  2. Select a version (or create a new version)
  3. In the Release Candidates panel, click Create new candidate (or the “+” button)
  4. The candidate creation process begins using the template configuration
  5. Configure any candidate-specific settings
  6. Click Create

What happens next:

  • The new candidate appears in the Release Candidates panel
  • You can create multiple candidates within the same version

Understanding Candidate Configuration

Release candidates inherit their base configuration from the template:

  • Image queue from the template
  • Authority from the template
  • Hardware profile requirements

Candidates allow you to:

  • Make minor adjustments if needed
  • Test variations within the same version
  • Iterate until the release is ready

Building the Image from Release Candidate

Each manufacturing image is made up from multiple images and as the team is iterating and making progress towards the final release version, an image in the image could get ready for release at given point, user can choose to mark this image verified, which locks the image to the exact versions of the artifacts making sure that same exact KAB ids are used to build the manifest. Once all images in the boot queue are marked verified, users can release the manufacturing build which then can be installed on devices.

To create a build for release candidate:

  1. Select a template from the Release Templates panel
  2. Select a version (or create a new version)
  3. In the Release Candidates panel, select the release version to build or create a new release candidate.
  4. Click on Build Image button.
  5. Select the directory to save the image.
  6. Click on Build
  7. This will start creating the build.

Managing Release Candidates

Viewing Candidate Details

When you select a candidate from the list, you see:

  • Candidate identifier or name
  • Creation date and creator information
  • Current status (pending, building, built, failed)
  • Associated version and template
  • Build history (if applicable)

Editing Release Candidates

To modify an existing candidate:

  1. Select the candidate from the Release Candidates panel
  2. Click Edit (or the edit icon)
  3. Modify candidate-specific settings
  4. Click Save

What happens:

  • Changes appear immediately
  • The candidate remains available for building
  • Other users see the updated configuration

Deleting Release Candidates

To remove a candidate:

  1. Select the candidate from the Release Candidates panel
  2. Click Delete (or the delete icon)
  3. Confirm the deletion
  4. The candidate is permanently removed

Important:

  • You cannot delete candidates that are currently building
  • Built images created from a candidate may still exist even after deleting the candidate
  • Consider whether deletion is necessary or if archiving is more appropriate

Building Images from Release Candidates

Initiating a Build

To build a deployable image from a release candidate:

  1. Select the release candidate
  2. Click Build Image (or the build button)
  3. The build process begins automatically
  4. Progress indicators show the build status

What happens during build:

  • The system assembles all images from the template queue
  • The configuration from the template and version is applied
  • A bootable device image is created
  • Build progress is displayed in real-time

Build Status Indicators

Pending:
The candidate is ready to be built but the build hasn’t started yet.

Building:
The build process is currently in progress. You can monitor progress but cannot modify the candidate.

Built:
The build completed successfully. The image is ready for deployment.

Failed:
The build encountered an error. Review error details to diagnose the issue.

After a Successful Build

Once a candidate is built successfully:

  • The built image is available in the project’s images
  • The image can be deployed to devices
  • The candidate can be rebuilt if needed
  • Build history is maintained

Offline Behavior

The Release Manager continues to function with limited capabilities when KOS Studio loses connection to the KOS Server:

Available Offline:

  • View all previously loaded templates, versions, and candidates
  • Browse release configurations
  • Review version and candidate details
  • Access information that was loaded before going offline

Disabled Offline:

  • Cannot create new versions
  • Cannot create new candidates
  • Cannot edit existing versions or candidates
  • Cannot delete versions or candidates
  • Cannot build images from candidates
  • Cannot sync with server updates

Indicators:

  • Standard offline indicators appear per KOS Studio conventions
  • Disabled features are clearly marked
  • Appropriate messaging explains limited functionality

Features Not Requiring Sync:
Some read-only operations that don’t require server connection may remain enabled, such as viewing and navigating through cached release data.

Practical Usage Scenarios

Creating a New Release Series

When starting a new release cycle:

  1. Administrator creates a template in Release Manager – Templates
  2. User opens Release Manager and selects the new template
  3. User creates first version (e.g., “v1.0”)
  4. User creates initial release candidate
  5. User builds and tests the candidate
  6. If issues are found, user creates another candidate with fixes
  7. Once satisfied, user locks the version to protect it

Iterating Within a Version

When refining a release before final deployment:

  1. Create first candidate and build it
  2. Test on devices and identify issues
  3. Create second candidate with corrections
  4. Build and test again
  5. Repeat until release is stable
  6. Lock the version when finalized
  7. Delete unsuccessful candidates to keep workspace clean

Managing Multiple Release Tracks

For organizations with parallel development:

  1. Use different templates for different release tracks (stable, beta, experimental)
  2. Create versions in each track independently
  3. Manage candidates separately for each track
  4. Build and deploy from appropriate tracks based on device type or customer
  5. Lock stable versions while continuing development in other tracks

Rolling Back to Previous Releases

When a new release has issues:

  1. Return to Release Manager
  2. Navigate to the previous stable version
  3. Select a known-good candidate from that version
  4. Rebuild the image
  5. Deploy the rebuilt image to affected devices
  6. Keep old versions unlocked and accessible for this purpose

Collaborative Release Management

When multiple team members manage releases:

  1. Administrators create and maintain templates
  2. Development team creates versions as features are completed
  3. QA team creates and tests candidates
  4. Release engineers build final images
  5. Lock versions after team approval
  6. Use clear naming and descriptions for coordination

Tips for Effective Release Management

  • Use consistent version naming: Establish and follow a version naming convention across your organization
  • Write detailed descriptions: Explain what’s new or different in each version and candidate
  • Lock finalized versions: Protect stable releases from accidental changes
  • Maintain release history: Keep old versions (locked) rather than deleting them for rollback capability
  • Coordinate with administrators: Communicate template needs to administrators
  • Use meaningful candidate names: If candidates have names, make them descriptive