dance-lessons-coach/scripts

dance-lessons-coach Scripts

This directory contains automation and management scripts for the dance-lessons-coach 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 dance-lessons-coach server lifecycle

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

#!/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
• Git SCM
• Go Build

dance-lessons-coach Specific

• ADR 0014: Version Management
• AGENTS.md Scripts Section
• Contributing Guide

---

Maintained by: dance-lessons-coach Team
License: MIT
Status: Actively developed