Version Management

Universal Release provides flexible version management supporting multiple schemes.

Version Schemes

Semantic Versioning (default)

global:
  versionScheme: semantic

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

• MAJOR: Breaking changes
• MINOR: New features (backward compatible)
• PATCH: Bug fixes
• PRERELEASE: alpha, beta, rc
• BUILD: Build metadata

Calendar Versioning

global:
  versionScheme: calver
  calverFormat: YYYY.MM.MICRO

Formats:

• YYYY.MM.DD - Date-based
• YYYY.MM.MICRO - Year.Month.Incrementing
• YY.0M.MICRO - Short year

Custom Versioning

global:
  versionScheme: custom
  customFormat: "v{year}.{month}.{build}"

Version Bumping

Manual Bump

# Bump specific level
release version --bump major    # 1.0.0 → 2.0.0
release version --bump minor    # 1.0.0 → 1.1.0
release version --bump patch    # 1.0.0 → 1.0.1

# Set explicit version
release version --set 2.0.0

Automatic Detection

Using conventional commits:

global:
  commitConvention: conventional-commits

# Auto-detect bump level from commits
release version --detect

Commit patterns:

• feat: → Minor bump
• fix: → Patch bump
• BREAKING CHANGE: → Major bump

Prerelease Versions

Create Prerelease

# Create alpha
release version --bump minor --pre alpha
# 1.0.0 → 1.1.0-alpha.0

# Create beta
release version --bump patch --pre beta
# 1.1.0 → 1.1.1-beta.0

# Create release candidate
release version --bump major --pre rc
# 1.1.1 → 2.0.0-rc.0

Publish Prerelease

release publish --tag beta

Graduate to Stable

# Remove prerelease identifier
release version --set 2.0.0
release publish --tag latest

Version Tags

npm Tags

# Publish to specific tag
release publish --tag latest    # Default
release publish --tag beta      # Prerelease
release publish --tag next      # Canary
release publish --tag legacy    # Old versions

Docker Tags

Multiple tags automatically created:

1.2.3    # Exact version
1.2      # Minor
1        # Major
latest   # Latest stable

Commit Conventions

Conventional Commits

global:
  commitConvention: conventional-commits

Format: <type>(<scope>): <subject>

Types:

• feat: - New feature (minor)
• fix: - Bug fix (patch)
• docs: - Documentation
• refactor: - Code refactoring
• test: - Tests
• chore: - Maintenance

Breaking changes:

feat!: breaking change
# or
feat: something

BREAKING CHANGE: explanation

Angular Convention

global:
  commitConvention: angular

Similar to conventional commits with Angular-specific types.

Version Reading

Universal Release reads versions from ecosystem-specific files:

Ecosystem	File	Field
npm	package.json	version
Cargo	Cargo.toml	version
Python	pyproject.toml	version
Go	Git tags	tag
Docker	Git tags	tag

Version Writing

Update version across all relevant files:

release version --set 2.0.0

This updates:

• package.json (npm)
• Cargo.toml (Cargo)
• pyproject.toml (Python)
• Creates Git tag (Go, Docker)

Programmatic API

import { VersionManager } from "@universal/release";

const vm = new VersionManager();

// Bump version
const newVersion = vm.bump("1.0.0", "minor"); // "1.1.0"

// Parse version
const parsed = vm.parse("1.2.3-beta.1");

// Compare versions
const isGreater = vm.compare("2.0.0", "1.9.9"); // 1

// Check satisfaction
const satisfies = vm.satisfies("1.2.3", "^1.0.0"); // true

Next Steps

• Architecture - System design
• CLI Commands - Full reference