start-os/agents/VERSION_BUMP.md

StartOS Version Bump Guide

This document explains how to bump the StartOS version across the entire codebase.

Overview

When bumping from version X.Y.Z-alpha.N to X.Y.Z-alpha.N+1, you need to update files in multiple locations across the repository. The // VERSION_BUMP comment markers indicate where changes are needed.

Files to Update

1. Core Rust Crate Version

File: core/Cargo.toml

Update the version string (line ~18):

version = "0.4.0-alpha.15" # VERSION_BUMP

File: core/Cargo.lock

This file is auto-generated. After updating Cargo.toml, run:

cd core
cargo check

This will update the version in Cargo.lock automatically.

2. Create New Version Migration Module

File: core/src/version/vX_Y_Z_alpha_N+1.rs

Create a new version file by copying the previous version and updating:

use exver::{PreReleaseSegment, VersionRange};

use super::v0_3_5::V0_3_0_COMPAT;
use super::{VersionT, v0_4_0_alpha_14};  // Update to previous version
use crate::prelude::*;

lazy_static::lazy_static! {
    static ref V0_4_0_alpha_15: exver::Version = exver::Version::new(
        [0, 4, 0],
        [PreReleaseSegment::String("alpha".into()), 15.into()]  // Update number
    );
}

#[derive(Clone, Copy, Debug, Default)]
pub struct Version;

impl VersionT for Version {
    type Previous = v0_4_0_alpha_14::Version;  // Update to previous version
    type PreUpRes = ();

    async fn pre_up(self) -> Result<Self::PreUpRes, Error> {
        Ok(())
    }
    fn semver(self) -> exver::Version {
        V0_4_0_alpha_15.clone()  // Update version name
    }
    fn compat(self) -> &'static VersionRange {
        &V0_3_0_COMPAT
    }
    #[instrument(skip_all)]
    fn up(self, _db: &mut Value, _: Self::PreUpRes) -> Result<Value, Error> {
        // Add migration logic here if needed
        Ok(Value::Null)
    }
    fn down(self, _db: &mut Value) -> Result<(), Error> {
        // Add rollback logic here if needed
        Ok(())
    }
}

3. Update Version Module Registry

File: core/src/version/mod.rs

Make changes in 5 locations:

Location 1: Module Declaration (~line 57)

Add the new module after the previous version:

mod v0_4_0_alpha_14;
mod v0_4_0_alpha_15;  // Add this

Location 2: Current Type Alias (~line 59)

Update the Current type and move the // VERSION_BUMP comment:

pub type Current = v0_4_0_alpha_15::Version; // VERSION_BUMP

Location 3: Version Enum (~line 175)

Remove // VERSION_BUMP from the previous version, add new variant, add comment:

    V0_4_0_alpha_14(Wrapper<v0_4_0_alpha_14::Version>),
    V0_4_0_alpha_15(Wrapper<v0_4_0_alpha_15::Version>), // VERSION_BUMP
    Other(exver::Version),

Location 4: as_version_t() Match (~line 233)

Remove // VERSION_BUMP, add new match arm, add comment:

            Self::V0_4_0_alpha_14(v) => DynVersion(Box::new(v.0)),
            Self::V0_4_0_alpha_15(v) => DynVersion(Box::new(v.0)), // VERSION_BUMP
            Self::Other(v) => {

Location 5: as_exver() Match (~line 284, inside #[cfg(test)])

Remove // VERSION_BUMP, add new match arm, add comment:

            Version::V0_4_0_alpha_14(Wrapper(x)) => x.semver(),
            Version::V0_4_0_alpha_15(Wrapper(x)) => x.semver(), // VERSION_BUMP
            Version::Other(x) => x.clone(),

4. SDK TypeScript Version

File: sdk/package/lib/StartSdk.ts

Update the OSVersion constant (~line 64):

export const OSVersion = testTypeVersion("0.4.0-alpha.15");

5. Web UI Package Version

File: web/package.json

Update the version field:

{
  "name": "startos-ui",
  "version": "0.4.0-alpha.15",
  ...
}

File: web/package-lock.json

This file is auto-generated, but it's faster to update manually. Find all instances of "startos-ui" and update the version field.

Verification Step

make

VERSION_BUMP Comment Pattern

The // VERSION_BUMP comment serves as a marker for where to make changes next time:

• Always remove it from the old location
• Add the new version entry
• Move the comment to mark the new location

This pattern helps you quickly find all the places that need updating in the next version bump.

Summary Checklist

• Update core/Cargo.toml version
• Create new core/src/version/vX_Y_Z_alpha_N+1.rs file
• Update core/src/version/mod.rs in 5 locations
• Run cargo check to update core/Cargo.lock
• Update sdk/package/lib/StartSdk.ts OSVersion
• Update web/package.json and web/package-lock.json version
• Verify all changes compile/build successfully

Migration Logic

The up() and down() methods in the version file handle database migrations:

• up(): Migrates the database from the previous version to this version
• down(): Rolls back from this version to the previous version
• pre_up(): Runs before migration, useful for pre-migration checks or data gathering

If no migration is needed, return Ok(Value::Null) for up() and Ok(()) for down().

For complex migrations, you may need to:

1. Update type PreUpRes to pass data between pre_up() and up()
2. Implement database transformations in the up() method
3. Implement reverse transformations in down() for rollback support