# Version Management Guide

This guide provides comprehensive instructions for managing versions in the dance-lessons-coach project.

## 📋 Table of Contents

1. [Semantic Versioning](#semantic-versioning)
2. [Version Bumping](#version-bumping)
3. [Release Process](#release-process)
4. [Changelog Management](#changelog-management)
5. [Git Tagging](#git-tagging)
6. [Troubleshooting](#troubleshooting)

## 📖 Semantic Versioning

dance-lessons-coach follows [Semantic Versioning 2.0.0](https://semver.org/):

### 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

```bash
# 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:
```bash
# VERSION file
MAJOR=1
MINOR=0
PATCH=1  # ← Increment this
PRERELEASE=""
```

2. Update Swagger annotation in `cmd/server/main.go`:
```go
// @version 1.0.1  # ← Update this
```

3. Regenerate documentation:
```bash
go generate ./...
```

## 🚀 Release Process

### Standard Release Workflow

```mermaid
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
```bash
# 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`:
```markdown
## [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

```bash
# 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

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

#### 5. Create Git Tag

```bash
# 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

```bash
# 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

```bash
# 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

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

## 📝 Changelog Management

### Changelog Format

Follow [Keep a Changelog](https://keepachangelog.com/) format:

```markdown
## [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

```markdown
## [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

```bash
# 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

```bash
# 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**:
```bash
# 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**:
```bash
# 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**:
```bash
# 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](https://semver.org/)
- [Keep a Changelog](https://keepachangelog.com/)
- [Conventional Commits](https://www.conventionalcommits.org/)
- [Git Tagging](https://git-scm.com/book/en/v2/Git-Basics-Tagging)

---

**Maintained by:** dance-lessons-coach Team  
**Last Updated:** 2026-04-05  
**Version:** 1.0