dance-lessons-coach/scripts/README.md

# 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