6.7 KiB
Wild Cloud Versioning Strategy
Current Implementation: Unified Versioning
Wild Cloud uses a single source of truth for versioning during the development phase (pre-v1.0.0). All components (API, CLI, Web, Package) share the same version number.
Version File Location
wild-cloud/VERSION
Single line file containing the current version (e.g., 0.1.1).
Why Unified Versioning Now?
- Simplicity: One version to track during development
- Tight Coupling: Components are developed and released together
- Development Phase: Pre-1.0.0, breaking changes are expected
- Easy Migration: Can transition to independent versioning later
Version Format
We follow Semantic Versioning 2.0.0:
MAJOR.MINOR.PATCH
Pre-1.0 Semantics (Current)
- MAJOR (0): Signals development phase
- MINOR (0.x): New features, may include breaking changes
- PATCH (0.1.x): Bug fixes, small improvements
Post-1.0 Semantics (Future)
- MAJOR: Breaking changes, incompatible API changes
- MINOR: New features, backward compatible
- PATCH: Bug fixes only
Workflows
Development Workflow (Iterating on Same Version)
During testing and iteration, update packages without bumping version:
# Make code changes
cd dist
make package-all
# Update existing release (keeps same version)
make release
Result: Existing release assets are replaced with new builds.
Creating a New Release
When ready for a new version:
# Option 1: Use helper script
./scripts/bump-version.sh 0.1.2
# Option 2: Manual steps
echo "0.1.2" > VERSION
git add VERSION
git commit -m "Bump version to 0.1.2"
git tag -a v0.1.2 -m "Wild Cloud Central v0.1.2"
# Build and release
cd dist
make package-all
make release
# Push to remote
cd ..
git push origin main v0.1.2
Result: New release with tag v0.1.2 is created.
Quick Reference
# Check current version
cat VERSION
# Bump version (helper script)
./scripts/bump-version.sh 0.2.0
# Build packages
cd dist && make package-all
# Create/update release
cd dist && make release
Release Behavior
The make release command is intelligent:
-
If release v0.1.1 exists: Updates package assets only
- Deletes old .deb files
- Uploads new .deb files
- Keeps release notes and metadata
-
If release v0.1.1 doesn't exist: Creates new release
- Creates Git tag
- Creates Gitea/GitHub release
- Uploads package assets
- Generates release notes
This allows rapid iteration during testing without creating dozens of releases.
Versioning Best Practices
When to Bump MINOR (0.x)
- New features added
- API endpoints added/changed
- Breaking changes (pre-1.0)
- Significant improvements
When to Bump PATCH (0.1.x)
- Bug fixes
- Security patches
- Performance improvements
- Documentation updates
- No user-facing changes
Pre-release Versions
For testing before official release:
echo "0.2.0-rc.1" > VERSION # Release candidate
echo "0.2.0-beta.1" > VERSION # Beta testing
echo "0.2.0-alpha.1" > VERSION # Alpha testing
Version Information in Components
API (Go)
Version injected at build time:
var Version = "dev" // Injected with -ldflags
Build command in Makefile:
go build -ldflags="-X main.Version=$(VERSION)"
CLI (Go)
Same pattern as API:
var Version = "dev"
Web (React)
Version in package.json (can stay at 0.0.0):
{
"version": "0.0.0"
}
Version available via API at runtime.
Debian Package
Version inserted into control file during packaging:
Package: wild-cloud-central
Version: 0.1.1
Future: Independent Component Versioning
When Wild Cloud matures (around v1.0.0), we may need independent versioning for components. This is documented in:
dist/future/independent-versioning.md
Migration Triggers
- CLI needs independent releases for CI/CD use
- API stability requires different versioning from UI
- Different release cadences for components
- Need to signal breaking API changes independently
Migration Path
The future design is already documented and can be implemented when needed:
- Create component VERSION files (api/VERSION, cli/VERSION, web/VERSION)
- Create MANIFEST.yaml for compatibility tracking
- Update build scripts to read multiple versions
- Add CLI version checking against API
- Support component-specific releases
Version Discovery
For Users
# From command line (future)
wild --version
# Output: Wild CLI v0.1.1 (API v0.1.1)
# From package
dpkg -l wild-cloud-central
# Output: ii wild-cloud-central 0.1.1 ...
For Developers
# Current version
cat VERSION
# Version in Makefile
cd dist && make version
# Version info in help
cd dist && make help
For Automation
# Read version programmatically
VERSION=$(cat VERSION)
# Validate version format
if [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
echo "Valid version: $VERSION"
fi
Tools and Scripts
Helper Scripts
scripts/bump-version.sh
- Validates version format
- Updates VERSION file
- Creates git commit and tag
- Provides next steps
./scripts/bump-version.sh 0.2.0
Makefile Targets
make version - Show current version and build info
make help - Shows version management instructions
make package-all - Build packages with current version
make release - Create/update release with current version
FAQ
Q: Can I release without bumping the version?
A: Yes! make release will update the existing release assets. Perfect for testing.
Q: How do I create a patch release?
A: Bump the PATCH number: echo "0.1.2" > VERSION
Q: What about pre-release versions?
A: Use semver pre-release format: 0.2.0-rc.1, 0.2.0-beta.1
Q: When should we switch to independent versioning?
A: When CLI needs separate releases or API needs stability guarantees (likely around v1.0.0)
Q: Can I manually edit the VERSION file?
A: Yes! It's just a text file. Or use ./scripts/bump-version.sh for automation.
Q: How does this work with git tags?
A: Git tags follow the version: v0.1.1. Create them manually or use the bump script.
Q: What if I forget to bump the version?
A: No problem! The release will update the existing version's assets.
References
- Semantic Versioning 2.0.0
- Keep a Changelog
- Future design:
dist/future/independent-versioning.md
Summary
Current State: Single VERSION file, unified versioning, perfect for development Future State: Independent component versioning when needed (documented in future/) Philosophy: Keep it simple until complexity is justified