Versioning & Release Strategy

PiVirt adheres to strict Semantic Versioning (SemVer) with automated patch tagging via GitHub Actions on every integration commit to develop.

Versioning Scheme

PiVirt follows Semantic Versioning (SemVer):

MAJOR.MINOR.PATCH

• MAJOR: Incompatible API changes
• MINOR: Backward-compatible new features
• PATCH: Backward-compatible bug fixes

Pre-release Versions

1.0.0-alpha.1
1.0.0-beta.1
1.0.0-rc.1

Build Metadata

1.0.0+build.123
1.0.0+git.abc123d

Version Components

Git Tags

# Create version tag
git tag -a v0.0.89 -m "Release v0.0.89"
git push origin v0.0.89

# List tags
git tag -l

# Show tag details
git show v0.0.89

Binary Version Info

# Check version
pivirtd --version
# Output: pivirtd v0.0.89 (commit: abc123d, built: 2024-01-15T10:30:00Z)

pvcli --version
# Output: pvcli v0.0.89 (commit: abc123d, built: 2024-01-15T10:30:00Z)

API Versioning

proto/pivirt/vm/v1/vm.proto

package pivirt.vm.v1;

service VMService {
  // API version: v1
}

Release Process

1. Prepare Release

# Update version in code
# Update CHANGELOG.md
# Update documentation

# Run tests
make test

# Build binaries
make build

# Build Docker images
make docker-build

2. Create Release Branch

# Create release branch
git checkout -b release/v0.0.89

# Commit changes
git add .
git commit -m "chore: prepare release v0.0.89"

# Push branch
git push origin release/v0.0.89

3. Create Release Tag

# Create annotated tag
git tag -a v0.0.89 -m "Release v0.0.89

Changes:
- Feature: Add live migration support
- Fix: Resolve storage pool issues
- Improve: Performance optimizations"

# Push tag
git push origin v0.0.89

4. Build Release Artifacts

# Build binaries
make release-build

# Build Docker images
make release-docker

# Push Docker images
make release-docker-push

5. Create GitHub Release

# Create release
gh release create v0.0.89 \
  --title "v0.0.89" \
  --notes "Release notes here" \
  ./bin/pivirtd-linux-amd64 \
  ./bin/pivirtd-linux-arm64 \
  ./bin/pvcli-linux-amd64 \
  ./bin/pvcli-darwin-arm64

Changelog

Format

## [0.0.89] - 2024-01-15

### Added
- Live migration support for VMs
- New storage pool types

### Changed
- Improved performance of VM creation
- Updated dependencies

### Fixed
- Fixed storage pool deletion issue
- Resolved network connectivity problems

### Security
- Updated TLS libraries
- Fixed authentication bypass vulnerability

Generate Changelog

# Generate from git log
git log v0.0.88..v0.0.89 --pretty=format:"* %s" > CHANGELOG.md

# Or use git-chglog
git-chglog -o CHANGELOG.md

API Compatibility

Backward Compatibility

// v1 API - stable
package pivirt.vm.v1;

// v2 API - new features, backward compatible
package pivirt.vm.v2;

Deprecation Policy

// Deprecated field
message VM {
  string old_field = 1 [deprecated = true];
  string new_field = 2;
}

Version in Configuration

/etc/pivirtd/config.yaml

version: "v0.0.89"

# Cluster version
cluster:
  version: "v0.0.89"
  min_version: "v0.0.85"  # Minimum compatible version

Upgrade Process

Check Current Version

pvcli cluster get prod-cluster -o json | jq '.version'

Upgrade Cluster

# Upgrade to new version
pvcli cluster upgrade --version v0.0.90 --strategy rolling

# Monitor upgrade
pvcli cluster upgrade status

Rollback

# Rollback to previous version
pvcli cluster upgrade --version v0.0.89 --strategy rolling

Troubleshooting

Version Mismatch

# Check component versions
pivirtd --version
pvcli --version

# Check cluster version
pvcli cluster get prod-cluster -o yaml

API Incompatibility

# Check API version
grpcurl -plaintext localhost:9001 list

# Check proto version
cat proto/pivirt/vm/v1/vm.proto | grep "package"

Related

• Build Guide
• CI/CD Guide