📝 docs: add comprehensive version management and CLI documentation

2026-04-05 11:28:11 +02:00
parent 3e8c50d80a
commit a5344d6ed8
13 changed files with 1864 additions and 1 deletions
--- a/scripts/README.md
+++ b/scripts/README.md
@@ -0,0 +1,313 @@
+# DanceLessonsCoach Scripts
+
+This directory contains automation and management scripts for the DanceLessonsCoach project.
+
+## 📁 Script Categories
+
+### 🚀 Server Management
+- **`start-server.sh`** - Start, stop, and manage the server lifecycle
+- **`test-opentelemetry.sh`** - Test OpenTelemetry integration with Jaeger
+
+### 📦 Version Management
+- **`version-bump.sh`** - Bump version numbers following Semantic Versioning
+- **`build-with-version.sh`** - Build binaries with embedded version information
+
+### 🔧 Build System
+- **`build.sh`** - Build server and CLI binaries
+
+### 📝 Documentation
+- **`generate-docs.sh`** - Generate Swagger/OpenAPI documentation (future)
+
+## 📋 Script Documentation
+
+### 1. Server Management (`start-server.sh`)
+
+**Manage the DanceLessonsCoach server lifecycle**
+
+```bash
+# Start the server
+./scripts/start-server.sh start
+
+# Stop the server
+./scripts/start-server.sh stop
+
+# Restart the server
+./scripts/start-server.sh restart
+
+# Check server status
+./scripts/start-server.sh status
+
+# View server logs
+./scripts/start-server.sh logs
+
+# Test API endpoints
+./scripts/start-server.sh test
+```
+
+**Features:**
+- Background process management
+- Log file rotation
+- PID file tracking
+- Graceful shutdown
+- Health check testing
+
+### 2. Version Bumping (`version-bump.sh`)
+
+**Automate version increments following Semantic Versioning**
+
+```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
+```
+
+**How it works:**
+1. Reads current version from `VERSION` file
+2. Increments appropriate version component
+3. Updates `VERSION` file
+4. Updates Swagger `@version` annotation in `main.go`
+5. Resets lower components when needed (e.g., minor bump sets patch to 0)
+
+**Semantic Versioning Rules:**
+- **MAJOR**: Breaking changes, major features
+- **MINOR**: Backwards-compatible features  
+- **PATCH**: Backwards-compatible bug fixes
+- **PRERELEASE**: alpha.1, beta.2, rc.1
+
+### 3. Build with Version (`build-with-version.sh`)
+
+**Build binaries with embedded version information**
+
+```bash
+# Build to default location (bin/server)
+./scripts/build-with-version.sh
+
+# Build to custom location
+./scripts/build-with-version.sh bin/my-server
+
+# Build with custom version (overrides VERSION file)
+VERSION="1.2.3" ./scripts/build-with-version.sh bin/server-custom
+```
+
+**Features:**
+- Automatically reads version from `VERSION` file
+- Injects version info using Go `ldflags`
+- Includes git commit hash
+- Includes build timestamp
+- Supports custom output paths
+
+**Version information includes:**
+- Semantic version (e.g., `1.0.0`)
+- Git commit hash (e.g., `abc123`)
+- Build date in UTC (e.g., `2026-04-05T08:00:00Z`)
+- Go version (e.g., `go1.26.1`)
+
+**Timezone Convention**: All timestamps use **UTC** for consistency across build environments.
+
+### 4. Build System (`build.sh`)
+
+**Build all project binaries**
+
+```bash
+# Build all binaries
+./scripts/build.sh
+
+# Build specific binary
+./scripts/build.sh server
+./scripts/build.sh greet
+```
+
+**Builds:**
+- `bin/server` - Web server binary
+- `bin/greet` - CLI greeting tool
+
+### 5. OpenTelemetry Testing (`test-opentelemetry.sh`)
+
+**Test OpenTelemetry integration with Jaeger**
+
+```bash
+# Start Jaeger and test tracing
+./scripts/test-opentelemetry.sh
+```
+
+**Features:**
+- Starts Jaeger in Docker
+- Builds server with OpenTelemetry
+- Makes test API calls
+- Shows Jaeger UI URL
+- Cleans up on exit
+
+## 🎯 Usage Patterns
+
+### Development Workflow
+```bash
+# 1. Build with version info
+./scripts/build-with-version.sh
+
+# 2. Start server
+./scripts/start-server.sh start
+
+# 3. Test endpoints
+./scripts/start-server.sh test
+
+# 4. Check version
+./bin/server --version
+```
+
+### Release Workflow
+```bash
+# 1. Bump version
+./scripts/version-bump.sh minor
+
+# 2. Update CHANGELOG
+vim AGENT_CHANGELOG.md
+
+# 3. Build release
+./scripts/build-with-version.sh bin/release/server-v1.1.0
+
+# 4. Test release
+./bin/release/server-v1.1.0 --version
+
+# 5. Commit and tag
+git commit -m "📖 chore: bump version to 1.1.0"
+git tag -a v1.1.0 -m "Release 1.1.0"
+```
+
+### CI/CD Integration
+```bash
+# In CI pipeline:
+./scripts/build-with-version.sh bin/server
+./scripts/start-server.sh start
+./scripts/start-server.sh test
+```
+
+## 🔧 Technical Details
+
+### Script Requirements
+- **Bash** (v4.0+ recommended)
+- **Git** (for version scripts)
+- **Go** (v1.26+)
+- **Docker** (for OpenTelemetry testing)
+
+### Environment Variables
+
+| Variable | Purpose | Example |
+|----------|---------|---------|
+| `VERSION` | Override version | `VERSION="1.2.3"` |
+| `MAJOR` | Major version | `MAJOR=1` |
+| `MINOR` | Minor version | `MINOR=0` |
+| `PATCH` | Patch version | `PATCH=0` |
+| `PRERELEASE` | Pre-release | `PRERELEASE="beta.1"` |
+
+### Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | Success |
+| `1` | General error |
+| `2` | Invalid arguments |
+| `3` | Missing dependencies |
+| `4` | Server already running |
+| `5` | Server not running |
+
+## 📝 Best Practices
+
+### Script Development
+1. **Idempotent operations**: Scripts should be safe to run multiple times
+2. **Clear error messages**: Help users understand what went wrong
+3. **Dry-run support**: Add `--dry-run` flag for safety
+4. **Logging**: Use consistent logging format
+5. **Documentation**: Keep README updated with new scripts
+
+### Script Usage
+1. **Check script help**: Most scripts support `--help`
+2. **Test in development**: Try new scripts locally first
+3. **Review changes**: Check what scripts modify before committing
+4. **Update documentation**: Add new scripts to this README
+5. **Follow conventions**: Use consistent naming and patterns
+
+## 🎓 Script Development Guide
+
+### Creating New Scripts
+
+1. **Name conventionally**: Use kebab-case (e.g., `do-thing.sh`)
+2. **Add shebang**: `#!/bin/bash`
+3. **Make executable**: `chmod +x script.sh`
+4. **Add error handling**: `set -e`
+5. **Document usage**: Add help text
+6. **Test thoroughly**: Verify in multiple scenarios
+7. **Add to README**: Document in this file
+
+### Script Template
+
+```bash
+#!/bin/bash
+# Script Name: description
+# Usage: ./script-name.sh [options]
+
+set -e  # Exit on error
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        -h|--help)
+            echo "Usage: $0 [options]"
+            exit 0
+            ;;
+        *)
+            echo "Unknown option: $1"
+            exit 2
+            ;;
+    esac
+done
+
+# Main logic here
+echo "Script executed successfully"
+
+exit 0
+```
+
+## 🔮 Future Scripts
+
+### Planned Scripts
+- **`release.sh`** - Full release automation
+- **`changelog.sh`** - Automated changelog generation
+- **`deploy.sh`** - Deployment automation
+- **`test-all.sh`** - Comprehensive test suite runner
+- **`lint.sh`** - Code quality checking
+
+### Requesting New Scripts
+1. **Open an issue**: Describe the automation need
+2. **Discuss approach**: Team review and design
+3. **Implement script**: Follow best practices
+4. **Test thoroughly**: Verify in multiple scenarios
+5. **Document**: Add to this README
+
+## 📚 Resources
+
+### Official Documentation
+- [Bash Guide](https://www.gnu.org/software/bash/)
+- [Git SCM](https://git-scm.com/)
+- [Go Build](https://golang.org/cmd/go/)
+
+### DanceLessonsCoach Specific
+- [ADR 0014: Version Management](adr/0014-version-management-lifecycle.md)
+- [AGENTS.md Scripts Section](#-scripts)
+- [Contributing Guide](CONTRIBUTING.md)
+
+---
+
+**Maintained by:** DanceLessonsCoach Team  
+**License:** MIT  
+**Status:** Actively developed
--- a/scripts/build-with-version.sh
+++ b/scripts/build-with-version.sh
@@ -0,0 +1,43 @@
+#!/bin/bash
+# Build DanceLessonsCoach with version information
+# Usage: ./scripts/build-with-version.sh [output_path]
+
+set -e
+
+# Default output path
+OUTPUT_PATH="${1:-bin/server}"
+
+# Get version from VERSION file or use default
+if [ -f "VERSION" ]; then
+    source VERSION
+    VERSION="$MAJOR.$MINOR.$PATCH${PRERELEASE:+-$PRERELEASE}"
+else
+    VERSION="1.0.0"
+fi
+
+# Get git information
+GIT_COMMIT=$(git rev-parse --short HEAD 2>/dev/null || echo "unknown")
+GIT_DATE=$(git log -1 --format=%cd --date=short 2>/dev/null || echo "unknown")
+
+# Build time (UTC for consistency)
+BUILD_DATE=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+echo "🔧 Building DanceLessonsCoach $VERSION"
+echo "   Commit: $GIT_COMMIT"
+echo "   Date: $GIT_DATE"
+echo "   Output: $OUTPUT_PATH"
+
+# Build with ldflags to inject version information
+go build \
+    -o "$OUTPUT_PATH" \
+    -ldflags="\
+        -X DanceLessonsCoach/pkg/version.Version=$VERSION \
+        -X DanceLessonsCoach/pkg/version.Commit=$GIT_COMMIT \
+        -X DanceLessonsCoach/pkg/version.Date=$BUILD_DATE \
+    " \
+    ./cmd/server
+
+echo "✅ Build complete: $OUTPUT_PATH"
+
+# Show version info
+"$OUTPUT_PATH" --version 2>/dev/null || echo "Version: $VERSION"
--- a/scripts/version-bump.sh
+++ b/scripts/version-bump.sh
@@ -0,0 +1,133 @@
+#!/bin/bash
+# DanceLessonsCoach Version Bump Script
+# Usage: ./scripts/version-bump.sh [major|minor|patch|pre|release]
+
+set -e
+
+# Load current version
+VERSION_FILE="VERSION"
+if [ ! -f "$VERSION_FILE" ]; then
+    echo "❌ Version file not found: $VERSION_FILE"
+    exit 1
+fi
+
+# Source version variables
+source "$VERSION_FILE"
+
+# Validate bump type
+BUMP_TYPE="${1:-patch}"
+case "$BUMP_TYPE" in
+    major|minor|patch|pre|release)
+        echo "📋 Bumping version: $BUMP_TYPE"
+        ;;
+    *)
+        echo "❌ Invalid bump type: $BUMP_TYPE"
+        echo "Usage: $0 [major|minor|patch|pre|release]"
+        exit 1
+        ;;
+esac
+
+# Bump version function
+bump_version() {
+    local type="$1"
+    
+    case "$type" in
+        major)
+            MAJOR=$((MAJOR + 1))
+            MINOR=0
+            PATCH=0
+            PRERELEASE=""
+            ;;
+        minor)
+            MINOR=$((MINOR + 1))
+            PATCH=0
+            PRERELEASE=""
+            ;;
+        patch)
+            PATCH=$((PATCH + 1))
+            PRERELEASE=""
+            ;;
+        pre)
+            if [ -z "$PRERELEASE" ]; then
+                PRERELEASE="alpha.1"
+            else
+                # Extract number and increment
+                if [[ "$PRERELEASE" =~ ^(alpha|beta|rc)\.([0-9]+)$ ]]; then
+                    PRE_TYPE="${BASH_REMATCH[1]}"
+                    PRE_NUM="${BASH_REMATCH[2]}"
+                    PRERELEASE="$PRE_TYPE.$((PRE_NUM + 1))"
+                else
+                    PRERELEASE="alpha.1"
+                fi
+            fi
+            ;;
+        release)
+            PRERELEASE=""
+            ;;
+    esac
+}
+
+# Bump the version
+bump_version "$BUMP_TYPE"
+
+# Calculate new version
+NEW_VERSION="$MAJOR.$MINOR.$PATCH"
+if [ -n "$PRERELEASE" ]; then
+    NEW_VERSION="$NEW_VERSION-$PRERELEASE"
+fi
+
+echo "🔢 Current version: $MAJOR.$MINOR.$PATCH${PRERELEASE:+-$PRERELEASE}"
+echo "🔜 New version: $NEW_VERSION"
+
+# Update VERSION file
+cat > "$VERSION_FILE" << VERSION_EOF
+# DanceLessonsCoach Version
+
+# Current Version (Semantic Versioning)
+MAJOR=$MAJOR
+MINOR=$MINOR
+PATCH=$PATCH
+PRERELEASE="$PRERELEASE"
+
+# Auto-generated fields (do not edit manually)
+BUILD_DATE=""
+GIT_COMMIT=""
+GIT_TAG=""
+
+# Version Format: {MAJOR}.{MINOR}.{PATCH}-{PRERELEASE}
+# Example: 1.0.0, 1.0.0-alpha.1, 2.3.4-beta.2
+
+# Semantic Versioning Rules:
+# - MAJOR: Breaking changes, major features
+# - MINOR: Backwards-compatible features
+# - PATCH: Backwards-compatible bug fixes
+# - PRERELEASE: alpha, beta, rc (pre-release versions)
+
+# Changelog Reference:
+# See AGENT_CHANGELOG.md for version history
+VERSION_EOF
+
+echo "✅ Updated VERSION file"
+
+# Update main.go Swagger version (cross-platform)
+MAIN_GO="cmd/server/main.go"
+if [ -f "$MAIN_GO" ]; then
+    # Create temporary file
+    TMP_FILE=$(mktemp)
+    
+    # Use awk for cross-platform sed replacement
+    awk -v new_version="$NEW_VERSION" '
+    {
+        if ($0 ~ /^\/\/ @version [0-9.]+/) {
+            print "// @version " new_version
+        } else {
+            print $0
+        }
+    }' "$MAIN_GO" > "$TMP_FILE"
+    
+    # Replace original file
+    mv "$TMP_FILE" "$MAIN_GO"
+    echo "✅ Updated Swagger version in main.go"
+fi
+
+echo "🎉 Version bump complete: $NEW_VERSION"