📝 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/AGENTS.md
+++ b/AGENTS.md
@@ -136,6 +136,22 @@ DanceLessonsCoach/

 ## 🚀 Server Management

+### Version Information
+
+The server provides runtime version information:
+
+```bash
+# Check version
+./bin/server --version
+
+# Output:
+DanceLessonsCoach Version Information:
+  Version:   1.0.0
+  Commit:    abc1234
+  Built:     2026-04-05T10:00:00+0000
+  Go:        go1.26.1
+```
+
 ### Using the Server Control Script

 A convenient shell script is provided for managing the server lifecycle:
@@ -874,6 +890,156 @@ defer cancel()
 - ✅ Comprehensive logging with Zerolog
 - ✅ Build system with binary output
 - ✅ Complete documentation with commit conventions
+- ✅ Version management with runtime info
+
+## 📦 Version Management
+
+DanceLessonsCoach uses a comprehensive version management system based on Semantic Versioning 2.0.0.
+
+### Version Information
+
+**Current Version:** `1.0.0` (see VERSION file)
+**Version Format:** `MAJOR.MINOR.PATCH-PRERELEASE`
+**SemVer Compliance:** ✅ Yes
+
+### Version Files
+
+```bash
+# VERSION file - Source of truth
+MAJOR=1
+MINOR=0
+PATCH=0
+PRERELEASE=""
+
+# Auto-generated fields
+BUILD_DATE=""
+GIT_COMMIT=""
+GIT_TAG=""
+```
+
+### Version Management Commands
+
+#### Check Version
+```bash
+# From VERSION file
+source VERSION && echo "$MAJOR.$MINOR.$PATCH${PRERELEASE:+-$PRERELEASE}"
+
+# From built binary
+./bin/server --version
+
+# From running server (future)
+curl http://localhost:8080/api/version
+```
+
+#### Bump Version
+```bash
+# Patch version (bug fixes)
+./scripts/version-bump.sh patch      # 1.0.0 → 1.0.1
+
+# Minor version (new features)
+./scripts/version-bump.sh minor      # 1.0.1 → 1.1.0
+
+# Major version (breaking changes)
+./scripts/version-bump.sh major      # 1.1.0 → 2.0.0
+
+# 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
+```
+
+#### Build with Version
+```bash
+# Development build
+./scripts/build-with-version.sh bin/server-dev
+
+# Release build
+go build -o bin/server \
+    -ldflags="\
+        -X 'DanceLessonsCoach/pkg/version.Version=1.0.0' \
+        -X 'DanceLessonsCoach/pkg/version.Commit=$(git rev-parse --short HEAD)' \
+        -X 'DanceLessonsCoach/pkg/version.Date=$(date +%Y-%m-%dT%H:%M:%S%z)' \
+    " \
+    ./cmd/server
+```
+
+### Semantic Versioning Rules
+
+| Part | 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 |
+
+### Release Lifecycle
+
+#### Development Workflow
+```mermaid
+graph LR
+    A[Feature Branch] --> B[PR to main]
+    B --> C[Auto-build with dev version]
+    C --> D[Deploy to dev/staging]
+```
+
+#### Release Workflow
+```mermaid
+graph LR
+    A[Bump version] --> B[Update CHANGELOG]
+    B --> C[Create git tag]
+    C --> D[Build release binaries]
+    D --> E[Push to GitHub Releases]
+    E --> F[Deploy to production]
+```
+
+### Version Package
+
+The `pkg/version` package provides runtime access to version information:
+
+```go
+package main
+
+import (
+    "DanceLessonsCoach/pkg/version"
+    "fmt"
+)
+
+func main() {
+    fmt.Println("Version:", version.Short())
+    fmt.Println("Full info:", version.Full())
+    fmt.Println("Info:", version.Info())
+}
+```
+
+**Functions:**
+- `version.Short()` - Returns version number (e.g., "1.0.0")
+- `version.Info()` - Returns short info string
+- `version.Full()` - Returns detailed version information
+
+### Implementation Status
+
+| Component | Status | Notes |
+|-----------|--------|-------|
+| Version Package | ✅ Complete | Runtime version access |
+| VERSION File | ✅ Complete | Source of truth |
+| Build Script | ✅ Complete | Version injection |
+| Version Command | ✅ Complete | `--version` flag |
+| Version Bump Script | 🟡 Partial | Basic functionality |
+| Git Tag Integration | 🟡 Planned | Release automation |
+| CI/CD Integration | 🟡 Planned | Pipeline automation |
+| Release Scripts | 🟡 Planned | Full release lifecycle |
+
+### Future Enhancements
+
+1. **Automated Changelog Generation**
+2. **Git Tag Automation**
+3. **CI/CD Pipeline Integration**
+4. **Version API Endpoint** (`GET /api/version`)
+5. **Dependency Version Tracking**
+6. **Security Vulnerability Alerts**
+
+See [ADR 0014](adr/0014-version-management-lifecycle.md) for complete version management architecture.

 ## 📝 Architecture Decision Records