Versioning

Dewy automatically detects the latest version of applications based on semantic versioning or calendar versioning and achieves continuous deployment. It provides comprehensive version management functionality including pre-release version management.

Overview

Versioning in Dewy is the core functionality of pull-based deployment. Based on version information retrieved from registries, it automatically determines whether new versions are available by comparing with currently running versions, and executes automatic deployment as needed.

Key Features:

• Complete support for Semantic Versioning (SemVer)
• Calendar Versioning (CalVer) support with flexible format specifiers
• Flexible management of pre-release versions
• Support for multiple version formats (v1.2.3 / 1.2.3)
• Support for environment-specific version strategies

Semantic Versioning Basics

Version Format

Dewy supports version management compliant with Semantic Versioning 2.0.0.

Basic format:

MAJOR.MINOR.PATCH

Examples:

• 1.2.3 - Version 1.2.3
• v1.2.3 - Version 1.2.3 with v prefix
• 2.0.0 - Major version 2.0.0

Version Number Meanings

Pre-release Versions

Pre-release versions are versions intended for testing and evaluation before official release.

Format:

MAJOR.MINOR.PATCH-<pre-release-identifier>

Common patterns:

• v1.2.3-alpha - Alpha version (initial testing)
• v1.2.3-beta.1 - Beta version 1 (feature-complete testing)
• v1.2.3-rc.1 - Release candidate 1 (final verification)

Build Metadata and Deployment Slots

Semantic versioning also supports build metadata, which is appended with a + sign. Dewy uses build metadata for deployment slot management, enabling blue/green deployment patterns.

Format:

MAJOR.MINOR.PATCH+<build-metadata>
MAJOR.MINOR.PATCH-<pre-release>+<build-metadata>

Common patterns:

• v1.2.3+blue - Stable version for Blue slot
• v1.2.3+green - Stable version for Green slot
• v1.2.3-rc.1+blue - Pre-release for Blue slot

Usage:

# Blue environment - only deploys versions with +blue metadata
dewy server --registry ghr://owner/repo --slot blue -- /opt/myapp/current/myapp

# Green environment - only deploys versions with +green metadata
dewy server --registry ghr://owner/repo --slot green -- /opt/myapp/current/myapp

# Without --slot - deploys any version (backward compatible)
dewy server --registry ghr://owner/repo -- /opt/myapp/current/myapp

Calendar Versioning (CalVer)

In addition to SemVer, Dewy supports Calendar Versioning (CalVer)—a versioning scheme based on release dates rather than compatibility semantics.

CalVer Format

CalVer is enabled by specifying a format string via the --calver option. The format consists of specifiers separated by dots.

Supported specifiers:

Format examples:

• YYYY.0M.0D.MICRO - Year, zero-padded month, zero-padded day, micro (e.g., 2024.01.15.3)
• YYYY.MM.DD - Year, month, day (e.g., 2024.1.9)
• YYYY.0M.MICRO - Year, zero-padded month, micro (e.g., 2024.06.3)

CalVer Usage

# CalVer with GitHub Releases
dewy server --registry ghr://owner/repo --calver YYYY.0M.0D.MICRO -- /opt/myapp/current/myapp

# CalVer with S3
dewy server --registry "s3://ap-northeast-1/releases/myapp" --calver YYYY.0M.MICRO -- /opt/myapp/current/myapp

# CalVer with pre-release versions
dewy server --registry "ghr://owner/repo?pre-release=true" --calver YYYY.0M.0D.MICRO -- /opt/myapp/current/myapp

Pre-release and Build Metadata with CalVer

CalVer supports pre-release identifiers and build metadata just like SemVer:

<calver>-<pre-release>+<build-metadata>

Examples:

• 2024.01.15.3-rc.1 - Release candidate
• 2024.06.0+blue - Blue deployment slot
• v2024.01.15.3-beta.2+green - Pre-release for Green slot with v prefix

Dewy's Version Detection Algorithm

Comparison Rules

Dewy implements version comparison algorithms for both SemVer and CalVer:

SemVer comparison:

1. MAJOR version comparison - Compare numerically, prioritize larger
2. MINOR version comparison - When MAJOR is same, compare numerically
3. PATCH version comparison - When MAJOR.MINOR is same, compare numerically
4. Pre-release version handling - Official version > Pre-release version; pre-release versions are compared as strings

CalVer comparison:

1. Segment-by-segment comparison - Each segment is compared numerically from left to right
2. Pre-release version handling - Same as SemVer: official version > pre-release version

Latest Version Determination

For all version tags retrieved from registry:

// Pseudo code
func findLatest(versions []string, allowPreRelease bool, calverFormat string) string {
    if calverFormat != "" {
        validVersions := filterValidCalVer(versions, calverFormat, allowPreRelease)
        return findMaxVersion(validVersions)
    }
    validVersions := filterValidSemVer(versions, allowPreRelease)
    return findMaxVersion(validVersions)
}

Processing flow:

1. Version format validation (SemVer or CalVer based on --calver option)
2. Filtering by pre-release settings
3. Numerical comparison and sorting
4. Maximum value selection

Registry-specific Version Management

GitHub Releases

Automatically detects versions from GitHub release tag names.

# Stable versions only (default)
dewy server --registry ghr://owner/repo

# Including pre-release versions
dewy server --registry "ghr://owner/repo?pre-release=true"

# Using CalVer format
dewy server --registry ghr://owner/repo --calver YYYY.0M.0D.MICRO

Grace period consideration:

AWS S3

Extracts versions from S3 object path structure.

Required path structure:

<path-prefix>/<version>/<artifact>

Configuration example:

# SemVer (default)
dewy server --registry "s3://ap-northeast-1/releases/myapp?pre-release=true"

# CalVer
dewy server --registry "s3://ap-northeast-1/releases/myapp" --calver YYYY.0M.MICRO

S3 arrangement example (SemVer):

releases/myapp/v1.2.4/myapp_linux_amd64.tar.gz
releases/myapp/v1.2.4/myapp_darwin_arm64.tar.gz
releases/myapp/v1.2.3/myapp_linux_amd64.tar.gz
releases/myapp/v1.2.3-rc.1/myapp_linux_amd64.tar.gz

S3 arrangement example (CalVer):

releases/myapp/2024.06.15.0/myapp_linux_amd64.tar.gz
releases/myapp/2024.06.15.1/myapp_linux_amd64.tar.gz
releases/myapp/2024.07.01.0/myapp_linux_amd64.tar.gz

Environment-specific Version Strategies

Production Environment

Recommended settings:

# Auto-deploy stable versions only
dewy server --registry ghr://company/myapp \
  --interval 300s \
  --log-format json -- /opt/myapp/current/myapp

Features:

• Exclude pre-release versions (pre-release=false)
• Longer polling intervals to reduce system load
• Prioritize monitoring ease with structured logs

Staging Environment

Recommended settings:

# Include pre-release versions for early testing
dewy server --registry "ghr://company/myapp?pre-release=true" \
  --interval 60s \
  --notifier "slack://staging-deploy?title=MyApp+Staging" \
  -- /opt/myapp/current/myapp

Features:

• Actively incorporate pre-release versions
• Short polling intervals for quick feedback
• Share with entire team through deployment notifications

Blue/Green Deployment

For blue/green deployment patterns, use build metadata to manage deployment slots:

Recommended settings:

# Blue environment
dewy server --registry ghr://company/myapp --slot blue \
  --interval 60s \
  --notifier "slack://production-deploy?title=MyApp+Blue" \
  -- /opt/myapp/current/myapp

# Green environment
dewy server --registry ghr://company/myapp --slot green \
  --interval 60s \
  --notifier "slack://production-deploy?title=MyApp+Green" \
  -- /opt/myapp/current/myapp

Features:

• Independent version control for each environment
• Zero-downtime deployment through traffic switching
• Easy rollback by switching traffic back
• Combine with pre-release for canary deployments

Deployment workflow:

# Step 1: Deploy to Green (standby)
gh release create v1.2.0+green --title "v1.2.0 for Green"

# Step 2: Verify Green environment

# Step 3: Switch traffic to Green (via load balancer)

# Step 4: Deploy same version to Blue
gh release create v1.2.0+blue --title "v1.2.0 for Blue"

# Both environments now running v1.2.0

Version Management Best Practices

Tagging Rules

Recommended tag naming conventions:

# Official releases
git tag v1.2.3
git tag v2.0.0

# Pre-releases
git tag v1.3.0-alpha
git tag v1.3.0-beta.1
git tag v1.3.0-rc.1

# Security fixes
git tag v1.2.4  # Security fix version for 1.2.3

Patterns to avoid:

# ❌ Non-structured naming
git tag latest
git tag stable

# ❌ Irregular naming
git tag v1.2.3-SNAPSHOT
git tag 1.2.3-final

Release Strategy

Staged release pattern:

1. alpha - Testing by internal developers
2. beta - Testing by limited users
3. rc (Release Candidate) - Testing in production-like conditions
4. Official version - Production environment deployment

Example:

v2.1.0-alpha    → Development environment
v2.1.0-beta.1   → Staging environment
v2.1.0-rc.1     → Staging environment (production-equivalent configuration)
v2.1.0          → Production environment

Troubleshooting

Common Issues and Solutions

Version not detected:

# Debug: Check available tags
curl -s https://api.github.com/repos/owner/repo/releases \
  | jq -r '.[].tag_name'

# Check detection process in logs
dewy server --log-format json -l debug --registry ghr://owner/repo

Unexpected version selected:

# Check pre-release settings
dewy server --registry "ghr://owner/repo?pre-release=false"  # Stable only
dewy server --registry "ghr://owner/repo?pre-release=true"   # Include pre-release

Access permission issues:

# Check GitHub Token
echo $GITHUB_TOKEN | cut -c1-10  # Display only first 10 characters
gh auth status  # Check authentication status with GitHub CLI

Related Topics

• Registry - Version detection source configuration and registry details
• Cache - Version information and artifact storage management
• Architecture - Dewy's overall configuration and deployment process
• FAQ - Frequently asked questions about versioning