dance-lessons-coach/documentation/version-management-guide.md

Version Management Guide

This guide provides comprehensive instructions for managing versions in the DanceLessonsCoach project.

📋 Table of Contents

1. Semantic Versioning
2. Version Bumping
3. Release Process
4. Changelog Management
5. Git Tagging
6. Troubleshooting

📖 Semantic Versioning

DanceLessonsCoach follows Semantic Versioning 2.0.0:

Version Format: MAJOR.MINOR.PATCH-PRERELEASE

Component	When to Increment	Examples
MAJOR	Breaking changes, major features	Database schema changes, API breaking changes
MINOR	Backwards-compatible features	New API endpoints, new functionality
PATCH	Backwards-compatible fixes	Bug fixes, performance improvements
PRERELEASE	Pre-release versions	alpha.1, beta.2, rc.1

Examples

• 1.0.0 - Initial stable release
• 1.1.0 - Added new feature (backwards-compatible)
• 1.1.1 - Bug fix (backwards-compatible)
• 2.0.0 - Breaking changes
• 2.0.0-alpha.1 - Pre-release version

🔢 Version Bumping

When to Bump Each Component

MAJOR Version (Breaking Changes)

• Database schema changes that require migrations
• API changes that break existing clients
• Configuration changes that require user action
• Dependency updates with breaking changes

Example: Removing or changing API endpoints, changing database schema

MINOR Version (Features)

• New API endpoints (backwards-compatible)
• New functionality that doesn't break existing features
• Enhancements to existing features

Example: Adding new API endpoints, adding new configuration options

PATCH Version (Bug Fixes)

• Bug fixes that don't change functionality
• Performance improvements
• Security patches
• Documentation updates

Example: Fixing bugs, improving performance, updating docs

How to Bump Version

Using the Version Bump Script

# Bump patch version (bug fixes)
./scripts/version-bump.sh patch      # 1.0.0 → 1.0.1

# Bump minor version (new features)
./scripts/version-bump.sh minor      # 1.0.1 → 1.1.0

# Bump major version (breaking changes)
./scripts/version-bump.sh major      # 1.1.0 → 2.0.0

# Create pre-release version
./scripts/version-bump.sh pre        # 2.0.0 → 2.0.0-alpha.1

# Release from pre-release
./scripts/version-bump.sh release     # 2.0.0-alpha.1 → 2.0.0

Manual Version Bumping

1. Edit VERSION file:

# VERSION file
MAJOR=1
MINOR=0
PATCH=1  # ← Increment this
PRERELEASE=""

2. Update Swagger annotation in cmd/server/main.go:

// @version 1.0.1  # ← Update this

3. Regenerate documentation:

go generate ./...

🚀 Release Process

Standard Release Workflow

graph TD
    A[Bump version] --> B[Update CHANGELOG]
    B --> C[Test changes]
    C --> D[Commit version bump]
    D --> E[Create git tag]
    E --> F[Build release]
    F --> G[Deploy to production]

Step-by-Step Release Checklist

1. Bump Version

# For patch release (bug fixes)
./scripts/version-bump.sh patch

# For minor release (new features)
./scripts/version-bump.sh minor

# For major release (breaking changes)
./scripts/version-bump.sh major

2. Update CHANGELOG

Edit AGENT_CHANGELOG.md:

## [1.0.1] - 2026-04-05

### Fixed
- Fixed bug in greeting validation
- Improved error handling

### Added
- New API endpoint for health checks

### Changed
- Updated Swagger documentation

3. Test Changes

# Run tests
go test ./...

# Test version endpoint
curl http://localhost:8080/api/version?format=json

# Test Swagger UI
open http://localhost:8080/swagger/

4. Commit Version Bump

git add VERSION cmd/server/main.go
git commit -m "📖 chore: bump version to 1.0.1"

5. Create Git Tag

# Annotated tag with message
git tag -a v1.0.1 -m "Release 1.0.1"

# Lightweight tag
git tag v1.0.1

6. Build Release

# Build with version info
./scripts/build-with-version.sh bin/release/server-v1.0.1

# Test the release binary
./bin/release/server-v1.0.1 --version

7. Deploy to Production

# Deploy the release binary
scp bin/release/server-v1.0.1 user@production:/opt/dance-lessons-coach/

# Restart service
systemctl restart dance-lessons-coach

8. Push to GitHub

# Push commit and tags
git push origin main --tags

📝 Changelog Management

Changelog Format

Follow Keep a Changelog format:

## [1.0.1] - YYYY-MM-DD

### Added
- New features here

### Changed
- Changes to existing functionality

### Deprecated
- Soon-to-be removed features

### Removed
- Removed features

### Fixed
- Bug fixes

### Security
- Security improvements

Changelog Best Practices

1. Group by type: Added, Changed, Deprecated, Removed, Fixed, Security
2. Be specific: "Fixed bug" → "Fixed validation error in greeting endpoint"
3. Link to issues: Reference GitHub issues when possible
4. Use imperative: "Add" not "Added", "Fix" not "Fixed"
5. One line per change: Keep it concise

Example CHANGELOG Entry

## [Unreleased]

### Added
- Add new `/api/version` endpoint for runtime version info
- Add hierarchical tagging to Swagger documentation

### Changed
- Refactor version management to use VERSION file
- Update Swagger annotations to use hierarchical tags

### Fixed
- Fix Swagger documentation generation for multi-package projects
- Fix version flag handling to work with both go run and compiled binary

🏷️ Git Tagging

Tag Naming Convention

# Annotated tags (recommended)
git tag -a v1.0.1 -m "Release 1.0.1"

# Lightweight tags
git tag v1.0.1

# Pre-release tags
git tag v2.0.0-alpha.1
git tag v2.0.0-beta.2
git tag v2.0.0-rc.1

Tag Management

# List all tags
git tag -l

# List tags matching pattern
git tag -l "v1.*"

# Delete local tag
git tag -d v1.0.1

# Delete remote tag
git push origin :refs/tags/v1.0.1

# Show tag details
git show v1.0.1

Tagging Best Practices

1. Annotated tags: Always use -a for release tags
2. SemVer compliance: Follow MAJOR.MINOR.PATCH format
3. Signed tags: Consider signing tags for security
4. Changelog sync: Tag after CHANGELOG update
5. CI/CD integration: Automate tag creation in pipeline

⚠️ Troubleshooting

Version Not Updating

Problem: Version shows old value after bump

Solution:

# 1. Check VERSION file
cat VERSION

# 2. Rebuild binary
./scripts/build-with-version.sh

# 3. Restart server
./scripts/start-server.sh restart

Swagger Docs Missing Endpoints

Problem: Greet endpoints missing from Swagger UI

Solution:

# Regenerate docs from project root
swag init -g ./cmd/server/main.go --parseDependency --parseInternal

# Move docs to correct location
mv docs/* pkg/server/docs/

# Restart server
./scripts/start-server.sh restart

Git Tag Issues

Problem: Tag push rejected

Solution:

# Delete local tag
git tag -d v1.0.1

# Delete remote tag
git push origin :refs/tags/v1.0.1

# Recreate tag
git tag -a v1.0.1 -m "Release 1.0.1"
git push origin v1.0.1

📚 Resources

• Semantic Versioning
• Keep a Changelog
• Conventional Commits
• Git Tagging

---

Maintained by: DanceLessonsCoach Team
Last Updated: 2026-04-05
Version: 1.0