Skip to main content

Release Conventions

How SKUs evolve through the release lifecycle and deployment pipeline.

Overview​

SKUs should change appropriately as code moves from development through staging to production, and as features are added or bugs are fixed.

Version Evolution​

Pre-Release (0.x.x)​

Use for development and beta versions:

0.1.0.API.EKS.20250101    # Initial development
0.2.0.API.EKS.20250105    # Feature added (pre-release)
0.2.1.API.EKS.20250106    # Bug fix (pre-release)

Guidelines:

  • Start at 0.1.0 for new projects
  • Increment minor version for features
  • Increment patch version for fixes
  • Pre-release versions have no backward compatibility guarantees

First Production Release (1.0.0)​

First stable release:

1.0.0.API.EKS.20250115    # First production release

Guidelines:

  • Ship 1.0.0 when ready for production
  • Implies backward compatibility from this point forward
  • Should have comprehensive tests and documentation

Patch Releases (x.y.Z)​

Bug fixes and minor improvements:

1.0.0.API.EKS.20250115    # Initial release
1.0.1.API.EKS.20250120    # Bug fix
1.0.2.API.EKS.20250125    # Another bug fix

Guidelines:

  • Increment patch version (Z) only
  • No breaking changes
  • No new features (use minor version for features)
  • Can include security patches, bug fixes, performance improvements

Minor Releases (x.Y.0)​

New features (backward compatible):

1.0.2.API.EKS.20250125    # Previous patch
1.1.0.API.EKS.20250201    # New features added
1.1.1.API.EKS.20250205    # Bug fix on 1.1.0

Guidelines:

  • Increment minor version (Y), reset patch to 0
  • Add new features without breaking existing functionality
  • Deprecate features (but keep them working)
  • Update documentation for new features

Major Releases (X.0.0)​

Breaking changes:

1.1.1.API.EKS.20250205    # Previous release
2.0.0.API.EKS.20250301    # Breaking changes

Guidelines:

  • Increment major version (X), reset minor and patch to 0
  • Breaking API changes allowed
  • Remove deprecated features
  • Major architectural changes
  • Provide migration guide

Build Date Evolution​

Same Version, Multiple Builds​

If you rebuild without code changes:

1.0.0.API.EKS.20250115    # Original build
1.0.0.API.EKS.20250116    # Rebuild (dependencies updated)

When to update build date:

  • Dependency updates
  • Configuration changes
  • Rebuild for different platform
  • Security patches in base images

Same Day, Multiple Versions​

Multiple releases in one day:

1.0.0.API.EKS.20250115    # Morning release
1.0.1.API.EKS.20250115    # Afternoon hotfix

Note: Version number distinguishes them, same build date is fine.

Platform Evolution​

Multi-Platform Deployments​

Same version across platforms:

1.0.0.API.EKS.20250115    # AWS Kubernetes
1.0.0.API.GKE.20250115    # Google Kubernetes
1.0.0.API.LM.20250115     # AWS Lambda (different implementation)

Guidelines:

  • Same version number across platforms
  • Same build date (built together)
  • Different platform codes
  • May have platform-specific optimizations

Platform Migration​

Moving from one platform to another:

# Old platform
1.5.3.API.EKS.20250110

# Migration to new platform
1.5.3.API.GKE.20250115    # Same version, new platform
1.5.4.API.GKE.20250120    # Continue normal evolution

Guidelines:

  • Keep same version number during migration
  • Update platform code only
  • Consider it a new build (new date)
  • Test thoroughly before switching traffic

Environment Promotion​

Dev → Staging → Production​

# Development
1.0.0.API.EKS.20250115

# Promoted to staging (same SKU)
1.0.0.API.EKS.20250115

# Promoted to production (same SKU)
1.0.0.API.EKS.20250115

Guidelines:

  • Use the same SKU across all environments
  • Don't change SKU when promoting
  • Use environment labels/tags separately
  • SKU represents the artifact, not the environment

Environment-Specific Builds​

If you must build separately per environment:

# Staging build
1.0.0.API.EKS.20250115

# Production build (different date)
1.0.0.API.EKS.20250116

Note: Avoid this pattern. Build once, deploy everywhere.

Hotfix Process​

Emergency Patch​

# Current production
1.2.5.API.EKS.20250110

# Hotfix branch
1.2.6.API.EKS.20250115    # Patch increment

Hotfix on Old Major Version​

# Current production
2.0.0.API.EKS.20250201

# Old version still supported
1.5.3.API.EKS.20250110    # Old version

# Hotfix for old version
1.5.4.API.EKS.20250215    # Patch on old major

Rollback Scenarios​

Rollback to Previous Version​

# Current (problematic)
1.3.0.API.EKS.20250120

# Rollback to
1.2.5.API.EKS.20250110    # Known good version

Guidelines:

  • Keep previous SKUs available for rollback
  • Don't create new SKU for rollback
  • Use the exact SKU that was working
  • Document rollback in deployment logs

Rollback with Fix​

# Current (problematic)
1.3.0.API.EKS.20250120

# Rollback to
1.2.5.API.EKS.20250110    # Temporary rollback

# Fix and release
1.3.1.API.EKS.20250121    # Fixed version

Deprecation Process​

Marking for Deprecation​

# Current version
2.0.0.API.EKS.20250201

# Add deprecation notice in docs
# Continue supporting for N months

# Remove in future major
3.0.0.API.EKS.20250601    # Deprecated features removed

Guidelines:

  • Announce deprecation in minor release notes
  • Keep deprecated features working for at least one major version
  • Provide migration path
  • Remove in next major version

Best Practices​

DO​

  1. Build once, deploy many times

    • Same SKU across dev, staging, production
    • Platform code reflects deployment target

  2. Increment versions semantically

    • Follow semver strictly
    • Document breaking changes clearly

  3. Update build date automatically

    • Generate in CI/CD pipeline
    • Use actual build timestamp

  4. Keep old versions accessible

    • For rollback scenarios
    • For long-term support

  5. Document version changes

    • Maintain CHANGELOG
    • Tag releases in git

DON'T​

  1. Don't skip versions

    • Go 1.0.0 → 1.0.1 → 1.0.2
    • Not 1.0.0 → 1.0.3

  2. Don't reuse SKUs

    • Each build gets a unique SKU
    • Never overwrite an existing SKU

  3. Don't make breaking changes in patches

    • Patches are bug fixes only
    • Use minor/major for changes

  4. Don't mix version strategies

    • Choose semantic versioning and stick to it
    • Be consistent across all services

CI/CD Integration​

GitHub Actions Example​

name: Build and Release

on:
  push:
    tags:
      - 'v*'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Generate SKU
        id: sku
        run: |
          VERSION=${GITHUB_REF#refs/tags/v}
          DATE=$(date +%Y%m%d)
          SKU="${VERSION}.API.EKS.${DATE}"
          echo "sku=${SKU}" >> $GITHUB_OUTPUT

      - name: Build with SKU
        env:
          ENGINE_SKU: ${{ steps.sku.outputs.sku }}
        run: |
          docker build \
            --build-arg SKU=${ENGINE_SKU} \
            -t myapp:${ENGINE_SKU} .

      - name: Tag and Push
        run: |
          docker tag myapp:${{ steps.sku.outputs.sku }} \
            registry/myapp:${{ steps.sku.outputs.sku }}
          docker push registry/myapp:${{ steps.sku.outputs.sku }}

See Also​