This document outlines the versioning strategy, semantic versioning practices, and automated version management for the SubWallet Services SDK.

• 📋 Overview
• 🏷️ Semantic Versioning
• 🔄 Version Management
• ⚙️ Automation Scripts
• 🔗 Dependency Management

The SubWallet Services SDK follows strict versioning guidelines to ensure compatibility, predictable updates, and clear communication of changes to consumers.

Current Version: 0.1.3-beta.5

We follow Semantic Versioning 2.0.0 specification:

MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]

• Breaking changes that require consumer code updates
• API signature changes
• Removed functionality
• Major architectural changes

Examples:

// v1.0.0 → v2.0.0
// Breaking: Method signature changed
- getUserBalance(address: string)
+ getUserBalance(address: string, options: BalanceOptions)

• New features that are backward compatible
• New API methods or properties
• Enhanced functionality
• New service integrations

Examples:

// v1.1.0 → v1.2.0
// Added: New method without breaking existing code
export class BalanceDetectionService {
  // Existing methods remain unchanged
  getBalance(address: string): Promise<Balance>
  
  // New method added
  getBalanceHistory(address: string): Promise<BalanceHistory[]>
}

• Bug fixes
• Performance improvements
• Documentation updates
• Internal refactoring without API changes

Examples:

// v1.1.1 → v1.1.2
// Fixed: Incorrect balance calculation
- const balance = amount * rate; // Bug: missing precision handling
+ const balance = new BigNumber(amount).multipliedBy(rate).toFixed();

0.1.3-beta.1
0.1.3-beta.2
0.1.3-beta.5  // Current

0.2.0-alpha.1
0.2.0-alpha.2

1.0.0-rc.1
1.0.0-rc.2

%%{init: {'theme':'dark'}}%%
graph LR
    Dev[Development] --> Alpha[Alpha Release]
    Alpha --> Beta[Beta Release]
    Beta --> RC[Release Candidate]
    RC --> Stable[Stable Release]
    
    Alpha --> Patch1[Alpha Patch]
    Beta --> Patch2[Beta Patch]
    RC --> Patch3[RC Patch]
    Stable --> Patch4[Stable Patch]
    
    Stable --> Minor[Minor Release]
    Minor --> Major[Major Release]
    
    style Dev fill:#2d3748,stroke:#4a5568,color:#fff
    style Alpha fill:#fbbf24,stroke:#f59e0b,color:#000
    style Beta fill:#3b82f6,stroke:#2563eb,color:#fff
    style RC fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style Stable fill:#10b981,stroke:#059669,color:#fff
    style Minor fill:#10b981,stroke:#059669,color:#fff
    style Major fill:#ef4444,stroke:#dc2626,color:#fff

The repository includes an automated version bumping script:

File: /scripts/bump-version.js

# Bump to specific version
node scripts/bump-version.js 0.1.4-beta.1

# Examples
node scripts/bump-version.js 0.2.0-alpha.1
node scripts/bump-version.js 1.0.0-rc.1
node scripts/bump-version.js 1.0.0

1. Multi-library Updates: Updates all library package.json files
2. Dependency Synchronization: Updates inter-library dependencies
3. App Updates: Synchronizes app dependencies with new library versions
4. Validation: Ensures version format compliance

Updated ./package.json with version 0.1.4-beta.1
Updated /libs/subwallet-services-sdk/package.json with version 0.1.4-beta.1
Updated /libs/cardano/package.json with version 0.1.4-beta.1
=========================================
Updating dependencies for app: /apps/subwallet-backend/package.json
Updated @subwallet-monorepos/subwallet-services-sdk to version 0.1.4-beta.1

// File: scripts/validate-version.ts
export function validateVersion(version: string): boolean {
  const semverRegex = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/;
  return semverRegex.test(version);
}

export function compareVersions(v1: string, v2: string): number {
  // Implementation for version comparison
  // Returns: -1 if v1 < v2, 0 if v1 = v2, 1 if v1 > v2
}

The SDK manages dependencies between multiple libraries in the monorepo:

{
  "name": "@subwallet-monorepos/subwallet-services-sdk",
  "dependencies": {
    "@subwallet-monorepos/subwallet-interfaces": "0.1.3-beta.5",
    "@subwallet-monorepos/subwallet-shared": "0.1.3-beta.5",
    "@subwallet-monorepos/cardano": "0.1.3-beta.5",
    "@subwallet-monorepos/xcm": "0.1.3-beta.5",
    "@subwallet-monorepos/swap-service": "0.1.3-beta.5"
  }
}

1. Lockstep Versioning: All libraries maintain the same version number
2. Automated Updates: Scripts automatically update all references
3. Consistency Validation: CI/CD checks ensure version consistency

%%{init: {'theme':'dark'}}%%
graph TD
    Change[Breaking Change] --> Analysis[Impact Analysis]
    Analysis --> Plan[Migration Plan]
    Plan --> Docs[Update Documentation]
    Docs --> Version[Bump Major Version]
    Version --> Notify[Notify Consumers]
    
    style Change fill:#ef4444,stroke:#dc2626,color:#fff
    style Analysis fill:#2d3748,stroke:#4a5568,color:#fff
    style Plan fill:#2d3748,stroke:#4a5568,color:#fff
    style Docs fill:#2d3748,stroke:#4a5568,color:#fff
    style Version fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style Notify fill:#10b981,stroke:#059669,color:#fff

1. Never manually edit version numbers - Always use automation scripts
2. Follow commit message conventions for automated changelog generation
3. Test thoroughly before version bumps
4. Document breaking changes with migration guides

1. Validate dependencies before releasing
2. Test in staging environment first
3. Coordinate with consuming teams for major releases
4. Maintain release notes with clear change descriptions

1. Pin to specific versions in production
2. Test pre-release versions in development
3. Follow upgrade guides for major version changes
4. Monitor deprecation warnings

Next Steps:

• Review Release Process
• Set up Environment Configuration
• Check Build Documentation

Navigation: ← Deployment Overview | Release Process → | Environments →