📝 docs: add comprehensive version management and CLI documentation
This commit is contained in:
313
scripts/README.md
Normal file
313
scripts/README.md
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user