arcodange/dance-lessons-coach
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

📝 docs: add comprehensive version management and CLI documentation

Browse Source
This commit is contained in:
Gabriel Radureau
2026-04-05 11:28:11 +02:00
parent 3e8c50d80a
commit a5344d6ed8
13 changed files with 1864 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

38
adr/0013-openapi-swagger-toolchain.md
View File

@@ -309,6 +309,44 @@ go install github.com/swaggo/swag/cmd/swag@latest
// @BasePath /api
package main
### Annotation Placement Considerations
**Current Approach**: Annotations in `cmd/server/main.go`
**Pros**:
- Follows Go community conventions
- Works seamlessly with swaggo
- Clear entry point for API documentation
**Cons**:
- Mixes API metadata with main package
- Less separation of concerns
**Alternative**: Annotations in `pkg/server/server.go`
**Pros**:
- Better organization (all server code together)
- More logical separation
- Easier maintenance
**Cons**:
- May require swag configuration changes
- Less conventional
- Potential tooling issues
**Decision**: Keep annotations in `cmd/server/main.go` for now
**Rationale**:
1. Follows established community patterns
2. Works reliably with current toolchain
3. Minimizes risk of breaking changes
4. Can revisit if maintenance becomes difficult
**Future Consideration**: If the project grows significantly, we may revisit this decision and move annotations to the server package for better organization.
```
### Implementation
# 3. Annotate handlers and models with hierarchical tags
// @Summary Get personalized greeting
// @Description Returns a greeting with the specified name

402
adr/0014-version-management-lifecycle.md Normal file
View File

@@ -0,0 +1,402 @@
# 14. Version Management and Release Lifecycle
**Date:** 2026-04-05
**Status:** ✅ Proposed
**Authors:** DanceLessonsCoach Team
**Decision Date:** 2026-04-05
**Implementation Status:** Partial (version package created, need to implement full lifecycle)
## Context
As DanceLessonsCoach matures, we need a robust version management and release lifecycle system to:
1. **Track versions consistently** across code, documentation, and deployments
2. **Automate version bumping** with clear semantic versioning rules
3. **Manage releases** through git tags and changelog integration
4. **Provide runtime version info** for debugging and support
5. **Support CI/CD pipelines** with automated version management
## Decision Drivers
* **Consistency**: Single source of truth for version information
* **Automation**: Reduce manual errors in version management
* **Traceability**: Link versions to git commits and builds
* **Semantic Versioning**: Follow industry standards (SemVer 2.0.0)
* **Runtime Visibility**: Expose version info in running applications
* **Release Management**: Support proper release tagging and changelog generation
* **CI/CD Integration**: Work seamlessly with automated build pipelines
## Decision
We will implement a **comprehensive version management system** with the following components:
### 1. Version Package (`pkg/version`)
**Purpose**: Centralized version information with runtime access
```go
package version
var (
Version = "1.0.0" // Semantic version
Commit = "" // Git commit hash
Date = "" // Build date
GoVersion = runtime.Version()
)
func Info() string
func Short() string
func Full() string
```
**Implementation Status**: ✅ Completed
### 2. Build-Time Version Injection
**Approach**: Use Go `ldflags` to inject version information during build
**Timezone Convention**: All timestamps use **UTC** for consistency
```bash
# Build command with version injection
go build \
-ldflags="\
-X 'DanceLessonsCoach/pkg/version.Version=1.0.0' \
-X 'DanceLessonsCoach/pkg/version.Commit=abc123' \
-X 'DanceLessonsCoach/pkg/version.Date=2026-04-05T10:00:00Z' # UTC format
" \
./cmd/server
```
**Rationale for UTC:**
- Consistent across all build environments
- Eliminates timezone ambiguity
- Follows ISO 8601 international standard
- Sortable and comparable
- CI/CD friendly
**Script**: `scripts/build-with-version.sh` ✅ Created
### 3. VERSION File
**Purpose**: Source of truth for version numbers
```bash
# VERSION file format
MAJOR=1
MINOR=0
PATCH=0
PRERELEASE="" # alpha.1, beta.2, rc.1, etc.
```
**Status**: ✅ Created
### 4. Version Bump Script
**Purpose**: Automated version increment following SemVer rules
```bash
# Usage: ./scripts/version-bump.sh [major|minor|patch|pre|release]
./scripts/version-bump.sh patch # 1.0.0 → 1.0.1
./scripts/version-bump.sh minor # 1.0.1 → 1.1.0
./scripts/version-bump.sh major # 1.1.0 → 2.0.0
./scripts/version-bump.sh pre # 2.0.0 → 2.0.0-alpha.1
./scripts/version-bump.sh release # 2.0.0-alpha.1 → 2.0.0
```
**Status**: 🟡 Partial (basic script created, needs refinement)
### 5. Command-Line Version Flag
**Implementation**: Add `--version` flag to all binaries
```bash
# Check version
dance-lessons-coach --version
# Output:
DanceLessonsCoach Version Information:
Version: 1.0.0
Commit: abc1234
Built: 2026-04-05T10:00:00+0000
Go: go1.26.1
```
**Status**: ✅ Completed
### 6. Git Tag Integration
**Workflow**:
```bash
# 1. Bump version
./scripts/version-bump.sh minor
# 2. Update CHANGELOG
# (Manual or automated process)
# 3. Commit changes
git commit -m "📖 chore: bump version to 1.1.0"
# 4. Create annotated tag
git tag -a v1.1.0 -m "Release 1.1.0"
# 5. Push with tags
git push origin main --tags
```
**Status**: 🟡 Planned
### 7. Release Lifecycle
#### Development Phase
```mermaid
graph LR
A[Feature Branch] --> B[PR to main]
B --> C[Auto-build with dev version]
C --> D[Deploy to dev/staging]
```
#### Release Phase
```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]
```
### 8. Semantic Versioning Rules
| Version Part | When to Increment | Example Changes |
|--------------|-------------------|-----------------|
| **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 |
### 9. Version Information Flow
```mermaid
graph TD
A[VERSION file] -->|source| B[Build Script]
B -->|ldflags| C[Compiled Binary]
C -->|runtime| D[Version Command]
C -->|runtime| E[API Response]
C -->|runtime| F[Logs/Metrics]
```
## Implementation Plan
### Phase 1: Core Version Management ✅ (Completed)
- [x] Create `pkg/version` package
- [x] Add version variables with ldflags support
- [x] Create VERSION file
- [x] Add `--version` flag to server
- [x] Create basic build script
### Phase 2: Version Bumping Automation 🟡 (In Progress)
- [ ] Complete version-bump.sh script
- [ ] Add pre-release version support
- [ ] Add validation and safety checks
- [ ] Create version validation script
### Phase 3: Release Lifecycle 🟡 (Planned)
- [ ] Create release preparation script
- [ ] Automate CHANGELOG updates
- [ ] Add git tag creation script
- [ ] Create GitHub release script
- [ ] Add release notes generation
### Phase 4: CI/CD Integration 🟡 (Planned)
- [ ] Add version info to CI builds
- [ ] Automate version bumping in CI
- [ ] Add version validation to PR checks
- [ ] Create release pipeline
- [ ] Add version to Docker images
## Rationale
### Why This Approach?
1. **Standard Compliance**: Follows Semantic Versioning 2.0.0
2. **Go Idiomatic**: Uses Go's ldflags for build-time injection
3. **Single Source of Truth**: VERSION file as canonical source
4. **Runtime Visibility**: Version info available in running apps
5. **Automation Friendly**: Scripts for CI/CD integration
6. **Traceability**: Links builds to git commits
7. **Extensible**: Can add more metadata as needed
### Alternatives Considered
#### Option 1: Hardcoded Version in main.go
- **❌ Rejected**: Manual updates, error-prone, no automation
- **Issue**: Version scattered across multiple files
#### Option 2: Git Tags Only
- **❌ Rejected**: No runtime access, requires git in production
- **Issue**: Can't access version in running containers
#### Option 3: External Version File (JSON/YAML)
- **❌ Rejected**: More complex, requires parsing
- **Issue**: Overkill for simple version management
#### Option 4: Build System Plugins
- **❌ Rejected**: Too complex, vendor lock-in
- **Issue**: Not portable across build systems
## Pros and Cons of Chosen Approach
### ✅ Advantages
1. **Simple**: Easy to understand and maintain
2. **Portable**: Works with any build system
3. **Runtime Access**: Version available in running apps
4. **Automatable**: Scripts for CI/CD integration
5. **Extensible**: Can add more metadata easily
6. **Standard**: Follows SemVer and Go conventions
### ❌ Disadvantages
1. **Manual Bumping**: Still requires manual version bumps
2. **Script Maintenance**: Need to maintain bash scripts
3. **Learning Curve**: Team needs to learn the workflow
4. **Error Potential**: Manual processes can have errors
## Validation
### Does this meet our requirements?
- ✅ **Consistency**: Single VERSION file as source of truth
- ✅ **Automation**: Scripts for version bumping and building
- ✅ **Traceability**: Git commit linked to builds
- ✅ **Semantic Versioning**: Follows SemVer 2.0.0 standards
- ✅ **Runtime Visibility**: Version available via `--version` flag
- ✅ **CI/CD Integration**: Scripts designed for pipeline use
- ✅ **Extensibility**: Can add more metadata as needed
### What's still needed?
- ❌ **Full automation**: Complete CI/CD pipeline integration
- ❌ **Release automation**: Git tag and release creation scripts
- ❌ **Changelog automation**: Automated changelog updates
- ❌ **Validation**: Comprehensive version validation
## Future Enhancements
### Short-Term (Next 3 Months)
1. **Complete version-bump.sh** with all features
2. **Add release preparation script**
3. **Automate CHANGELOG updates**
4. **Add git tag integration**
5. **Create validation scripts**
### Medium-Term (3-6 Months)
1. **CI/CD pipeline integration**
2. **Automated release notes**
3. **Docker image versioning**
4. **Version API endpoint**
5. **Metrics and monitoring**
### Long-Term (6-12 Months)
1. **Automated version bumping** based on commit messages
2. **Monorepo version management**
3. **Dependency version tracking**
4. **Security vulnerability tracking**
5. **Deprecation policies**
## Migration Plan
### From Current State
1. **Replace hardcoded version** in main.go with VERSION file
2. **Update build scripts** to use new version system
3. **Add version command** to all binaries
4. **Document workflow** for team
5. **Train team** on new version management
### For Existing Deployments
1. **Gradual rollout**: Update version info on next deploy
2. **Backward compatibility**: Keep old version formats temporarily
3. **Monitoring**: Track version adoption
4. **Documentation**: Update all docs with new version info
## Success Metrics
1. **100% of builds** include proper version information
2. **0 manual version errors** in releases
3. **All team members** can bump versions correctly
4. **CI/CD pipeline** handles versioning automatically
5. **Release process** is documented and followed
6. **Version visibility** in production environments
## References
- [Semantic Versioning 2.0.0](https://semver.org/)
- [Go ldflags Documentation](https://pkg.go.dev/cmd/link)
- [Git Tags Documentation](https://git-scm.com/book/en/v2/Git-Basics-Tagging)
- [Conventional Commits](https://www.conventionalcommits.org/)
## Appendix: Version Management Commands
### Check Current Version
```bash
# From VERSION file
source VERSION && echo "$MAJOR.$MINOR.$PATCH${PRERELEASE:+-$PRERELEASE}"
# From built binary
./bin/server --version
```
### Bump Version
```bash
# Patch version (bug fixes)
./scripts/version-bump.sh patch
# Minor version (new features)
./scripts/version-bump.sh minor
# Major version (breaking changes)
./scripts/version-bump.sh major
# Pre-release version
./scripts/version-bump.sh pre
# Release from pre-release
./scripts/version-bump.sh release
```
### 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
```
### Create Release
```bash
# 1. Bump version
./scripts/version-bump.sh minor
# 2. Update CHANGELOG
# Edit AGENT_CHANGELOG.md
# 3. Commit version bump
git commit -m "📖 chore: bump version to 1.1.0"
# 4. Create annotated tag
git tag -a v1.1.0 -m "Release 1.1.0"
# 5. Push with tags
git push origin main --tags
```
---
**Status:** Proposed
**Next Review:** 2026-04-12
**Implementation Owner:** DanceLessonsCoach Team
**Approvers Needed:** @gabrielradureau

198
adr/0015-cli-subcommands-cobra.md Normal file
View File

@@ -0,0 +1,198 @@
# 15. CLI Subcommands and Flag Management with Cobra
**Date:** 2026-04-05
**Status:** 🟡 Proposed
**Authors:** DanceLessonsCoach Team
**Decision Date:** TBD
**Implementation Status:** Not Started
## Context
As DanceLessonsCoach grows, we need a more robust and maintainable CLI structure. Currently, we use simple flag parsing (`--version`), but this approach has limitations:
1. **Limited scalability**: Adding more commands/flags becomes messy
2. **Poor user experience**: No built-in help, completion, or validation
3. **Hard to maintain**: Manual flag parsing is error-prone
4. **No subcommands**: Can't easily add commands like `server start`, `server stop`, etc.
## Decision Drivers
* **Scalability**: Support growing CLI needs as project expands
* **User Experience**: Provide professional CLI with help, completion, validation
* **Maintainability**: Easy to add/remove commands and flags
* **Standards**: Follow industry best practices for CLI tools
* **Extensibility**: Support future commands (migrate, seed, etc.)
* **Integration**: Work well with existing config system
## Decision
We will adopt **Cobra** as our CLI framework. Cobra is a mature, widely-used library for building modern CLI applications in Go.
### Selected Solution: Cobra CLI Framework
**Repository**: https://github.com/spf13/cobra
**Version**: v1.8.0 (or latest stable)
### Key Features
1. **Subcommands**: `server start`, `server stop`, `migrate`, etc.
2. **Flags**: `--config`, `--env`, `--verbose`, etc.
3. **Help System**: Automatic `--help` generation
4. **Shell Completion**: Built-in support
5. **Validation**: Type-safe flag parsing
6. **Middleware**: Pre/post command hooks
### Implementation Plan
#### Phase 1: Basic Integration (Next Sprint)
```go
var rootCmd = &cobra.Command{
Use: "dance-lessons-coach",
Short: "DanceLessonsCoach - API server and CLI tools",
Long: `DanceLessonsCoach provides greeting services and API management.
To begin working with DanceLessonsCoach, run:
dance-lessons-coach server --help`,
SilenceUsage: true,
}
var versionCmd = &cobra.Command{
Use: "version",
Short: "Print version information",
Run: func(cmd *cobra.Command, args []string) {
fmt.Println(version.Full())
},
}
var serverCmd = &cobra.Command{
Use: "server",
Short: "Start the DanceLessonsCoach server",
Run: func(cmd *cobra.Command, args []string) {
// Load config and start server
cfg, err := config.LoadConfig()
if err != nil {
log.Fatal().Err(err).Msg("Failed to load configuration")
}
server := server.NewServer(cfg, context.Background())
if err := server.Run(); err != nil {
log.Fatal().Err(err).Msg("Server failed")
}
},
}
func init() {
rootCmd.AddCommand(versionCmd)
rootCmd.AddCommand(serverCmd)
// Add flags to server command
serverCmd.Flags().String("config", "", "Config file path")
serverCmd.Flags().String("env", "", "Environment (dev, staging, prod)")
serverCmd.Flags().Bool("debug", false, "Enable debug logging")
}
func main() {
if err := rootCmd.Execute(); err != nil {
log.Fatal().Err(err).Msg("CLI execution failed")
}
}
```
#### Phase 2: Advanced Features (Future)
- **Subcommand groups**: `server`, `db`, `migrate`, `tools`
- **Persistent flags**: Global flags like `--config`, `--env`
- **Command aliases**: Shorter command names
- **Custom help templates**: Branded help output
- **Shell completion scripts**: Generate completion for bash/zsh/fish
#### Phase 3: Migration (Ongoing)
- Migrate existing flags to Cobra
- Deprecate old flag parsing
- Update documentation
- Add new commands as needed
### Migration Strategy
1. **Incremental adoption**: Start with version command, then server command
2. **Backward compatibility**: Support old flags during transition
3. **Documentation**: Update README with new CLI usage
4. **Testing**: Ensure all existing functionality works
### Command Structure Proposal
```bash
# Main commands
dance-lessons-coach server # Start the server
dance-lessons-coach version # Show version
dance-lessons-coach migrate # Database migrations
dance-lessons-coach config # Config management
# Server subcommands
dance-lessons-coach server start # Start server
dance-lessons-coach server stop # Stop server
dance-lessons-coach server restart # Restart server
dance-lessons-coach server status # Server status
# Global flags
dance-lessons-coach --help # Show help
dance-lessons-coach --version # Show version (shortcut)
dance-lessons-coach --config /path/to/config.yaml
# Example usage
dance-lessons-coach server start --env production --debug
dance-lessons-coach migrate up
dance-lessons-coach config validate
```
### Pros and Cons of Cobra
#### ✅ Advantages
1. **Industry Standard**: Used by Kubernetes, Hugo, etcd, and many others
2. **Mature Ecosystem**: Well-documented, widely adopted
3. **Feature Rich**: Help, completion, validation built-in
4. **Extensible**: Easy to add new commands
5. **Go Idiomatic**: Fits well with Go patterns
6. **Good Documentation**: Excellent docs and examples
#### ❌ Disadvantages
1. **Learning Curve**: New patterns to learn
2. **Migration Effort**: Need to refactor existing code
3. **Slight Overhead**: More complex than simple flag parsing
4. **Dependency**: Adds cobra to project
### Validation
**Does this meet our requirements?**
- ✅ **Scalability**: Easy to add new commands
- ✅ **User Experience**: Professional CLI with help/completion
- ✅ **Maintainability**: Clean, structured code
- ✅ **Standards**: Follows industry best practices
- ✅ **Extensibility**: Supports future growth
- ✅ **Integration**: Works with existing config system
**What's still needed?**
- ❌ **Implementation**: Actual cobra integration
- ❌ **Migration**: Move existing flags to cobra
- ❌ **Documentation**: Update docs with new CLI
- ❌ **Testing**: Ensure all functionality works
### Future Enhancements
1. **Add more commands**: `migrate`, `config`, `db`, etc.
2. **Improve help**: Custom templates, examples
3. **Add completion**: Shell completion scripts
4. **Enhance validation**: Better error messages
5. **Add aliases**: Shorter command names
### References
- [Cobra GitHub](https://github.com/spf13/cobra)
- [Cobra Documentation](https://cobra.dev/)
- [CLI Guidelines](https://clig.dev/)
- [Go CLI Best Practices](https://github.com/clig-dev/clig)
---
**Status:** Proposed
**Next Review:** 2026-04-12
**Implementation Owner:** DanceLessonsCoach Team
**Approvers Needed:** @gabrielradureau