Gabriel Radureau
c1e628f339
Documentation Updates: - Enhanced AGENTS.md with user authentication details - Updated README.md with authentication API documentation - Added CONTRIBUTING.md guidelines for BDD testing - Version management guide improvements - Local CI/CD testing documentation Project Infrastructure: - Updated .gitignore for new file patterns - Enhanced git hooks documentation - YAML linting configuration - Script improvements and organization - Configuration management updates API Enhancements: - Greet service integration with authentication - Server middleware for JWT validation - Telemetry improvements - Version management utilities Generated by Mistral Vibe. Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
365 lines
7.6 KiB
Markdown
365 lines
7.6 KiB
Markdown
# Version Management Guide
|
|
|
|
This guide provides comprehensive instructions for managing versions in the dance-lessons-coach project.
|
|
|
|
## 📋 Table of Contents
|
|
|
|
1. [Semantic Versioning](#semantic-versioning)
|
|
2. [Version Bumping](#version-bumping)
|
|
3. [Release Process](#release-process)
|
|
4. [Changelog Management](#changelog-management)
|
|
5. [Git Tagging](#git-tagging)
|
|
6. [Troubleshooting](#troubleshooting)
|
|
|
|
## 📖 Semantic Versioning
|
|
|
|
dance-lessons-coach follows [Semantic Versioning 2.0.0](https://semver.org/):
|
|
|
|
### Version Format: `MAJOR.MINOR.PATCH-PRERELEASE`
|
|
|
|
| Component | 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` |
|
|
|
|
### Examples
|
|
- `1.0.0` - Initial stable release
|
|
- `1.1.0` - Added new feature (backwards-compatible)
|
|
- `1.1.1` - Bug fix (backwards-compatible)
|
|
- `2.0.0` - Breaking changes
|
|
- `2.0.0-alpha.1` - Pre-release version
|
|
|
|
## 🔢 Version Bumping
|
|
|
|
### When to Bump Each Component
|
|
|
|
#### MAJOR Version (Breaking Changes)
|
|
- **Database schema changes** that require migrations
|
|
- **API changes** that break existing clients
|
|
- **Configuration changes** that require user action
|
|
- **Dependency updates** with breaking changes
|
|
|
|
**Example**: Removing or changing API endpoints, changing database schema
|
|
|
|
#### MINOR Version (Features)
|
|
- **New API endpoints** (backwards-compatible)
|
|
- **New functionality** that doesn't break existing features
|
|
- **Enhancements** to existing features
|
|
|
|
**Example**: Adding new API endpoints, adding new configuration options
|
|
|
|
#### PATCH Version (Bug Fixes)
|
|
- **Bug fixes** that don't change functionality
|
|
- **Performance improvements**
|
|
- **Security patches**
|
|
- **Documentation updates**
|
|
|
|
**Example**: Fixing bugs, improving performance, updating docs
|
|
|
|
### How to Bump Version
|
|
|
|
#### Using the Version Bump Script
|
|
|
|
```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
|
|
```
|
|
|
|
#### Manual Version Bumping
|
|
|
|
1. Edit `VERSION` file:
|
|
```bash
|
|
# VERSION file
|
|
MAJOR=1
|
|
MINOR=0
|
|
PATCH=1 # ← Increment this
|
|
PRERELEASE=""
|
|
```
|
|
|
|
2. Update Swagger annotation in `cmd/server/main.go`:
|
|
```go
|
|
// @version 1.0.1 # ← Update this
|
|
```
|
|
|
|
3. Regenerate documentation:
|
|
```bash
|
|
go generate ./...
|
|
```
|
|
|
|
## 🚀 Release Process
|
|
|
|
### Standard Release Workflow
|
|
|
|
```mermaid
|
|
graph TD
|
|
A[Bump version] --> B[Update CHANGELOG]
|
|
B --> C[Test changes]
|
|
C --> D[Commit version bump]
|
|
D --> E[Create git tag]
|
|
E --> F[Build release]
|
|
F --> G[Deploy to production]
|
|
```
|
|
|
|
### Step-by-Step Release Checklist
|
|
|
|
#### 1. Bump Version
|
|
```bash
|
|
# For patch release (bug fixes)
|
|
./scripts/version-bump.sh patch
|
|
|
|
# For minor release (new features)
|
|
./scripts/version-bump.sh minor
|
|
|
|
# For major release (breaking changes)
|
|
./scripts/version-bump.sh major
|
|
```
|
|
|
|
#### 2. Update CHANGELOG
|
|
|
|
Edit `AGENT_CHANGELOG.md`:
|
|
```markdown
|
|
## [1.0.1] - 2026-04-05
|
|
|
|
### Fixed
|
|
- Fixed bug in greeting validation
|
|
- Improved error handling
|
|
|
|
### Added
|
|
- New API endpoint for health checks
|
|
|
|
### Changed
|
|
- Updated Swagger documentation
|
|
```
|
|
|
|
#### 3. Test Changes
|
|
|
|
```bash
|
|
# Run tests
|
|
go test ./...
|
|
|
|
# Test version endpoint
|
|
curl http://localhost:8080/api/version?format=json
|
|
|
|
# Test Swagger UI
|
|
open http://localhost:8080/swagger/
|
|
```
|
|
|
|
#### 4. Commit Version Bump
|
|
|
|
```bash
|
|
git add VERSION cmd/server/main.go
|
|
git commit -m "📖 chore: bump version to 1.0.1"
|
|
```
|
|
|
|
#### 5. Create Git Tag
|
|
|
|
```bash
|
|
# Annotated tag with message
|
|
git tag -a v1.0.1 -m "Release 1.0.1"
|
|
|
|
# Lightweight tag
|
|
git tag v1.0.1
|
|
```
|
|
|
|
#### 6. Build Release
|
|
|
|
```bash
|
|
# Build with version info
|
|
./scripts/build-with-version.sh bin/release/server-v1.0.1
|
|
|
|
# Test the release binary
|
|
./bin/release/server-v1.0.1 --version
|
|
```
|
|
|
|
#### 7. Deploy to Production
|
|
|
|
```bash
|
|
# Deploy the release binary
|
|
scp bin/release/server-v1.0.1 user@production:/opt/dance-lessons-coach/
|
|
|
|
# Restart service
|
|
systemctl restart dance-lessons-coach
|
|
```
|
|
|
|
#### 8. Push to GitHub
|
|
|
|
```bash
|
|
# Push commit and tags
|
|
git push origin main --tags
|
|
```
|
|
|
|
## 📝 Changelog Management
|
|
|
|
### Changelog Format
|
|
|
|
Follow [Keep a Changelog](https://keepachangelog.com/) format:
|
|
|
|
```markdown
|
|
## [1.0.1] - YYYY-MM-DD
|
|
|
|
### Added
|
|
- New features here
|
|
|
|
### Changed
|
|
- Changes to existing functionality
|
|
|
|
### Deprecated
|
|
- Soon-to-be removed features
|
|
|
|
### Removed
|
|
- Removed features
|
|
|
|
### Fixed
|
|
- Bug fixes
|
|
|
|
### Security
|
|
- Security improvements
|
|
```
|
|
|
|
### Changelog Best Practices
|
|
|
|
1. **Group by type**: Added, Changed, Deprecated, Removed, Fixed, Security
|
|
2. **Be specific**: "Fixed bug" → "Fixed validation error in greeting endpoint"
|
|
3. **Link to issues**: Reference GitHub issues when possible
|
|
4. **Use imperative**: "Add" not "Added", "Fix" not "Fixed"
|
|
5. **One line per change**: Keep it concise
|
|
|
|
### Example CHANGELOG Entry
|
|
|
|
```markdown
|
|
## [Unreleased]
|
|
|
|
### Added
|
|
- Add new `/api/version` endpoint for runtime version info
|
|
- Add hierarchical tagging to Swagger documentation
|
|
|
|
### Changed
|
|
- Refactor version management to use VERSION file
|
|
- Update Swagger annotations to use hierarchical tags
|
|
|
|
### Fixed
|
|
- Fix Swagger documentation generation for multi-package projects
|
|
- Fix version flag handling to work with both go run and compiled binary
|
|
```
|
|
|
|
## 🏷️ Git Tagging
|
|
|
|
### Tag Naming Convention
|
|
|
|
```bash
|
|
# Annotated tags (recommended)
|
|
git tag -a v1.0.1 -m "Release 1.0.1"
|
|
|
|
# Lightweight tags
|
|
git tag v1.0.1
|
|
|
|
# Pre-release tags
|
|
git tag v2.0.0-alpha.1
|
|
git tag v2.0.0-beta.2
|
|
git tag v2.0.0-rc.1
|
|
```
|
|
|
|
### Tag Management
|
|
|
|
```bash
|
|
# List all tags
|
|
git tag -l
|
|
|
|
# List tags matching pattern
|
|
git tag -l "v1.*"
|
|
|
|
# Delete local tag
|
|
git tag -d v1.0.1
|
|
|
|
# Delete remote tag
|
|
git push origin :refs/tags/v1.0.1
|
|
|
|
# Show tag details
|
|
git show v1.0.1
|
|
```
|
|
|
|
### Tagging Best Practices
|
|
|
|
1. **Annotated tags**: Always use `-a` for release tags
|
|
2. **SemVer compliance**: Follow MAJOR.MINOR.PATCH format
|
|
3. **Signed tags**: Consider signing tags for security
|
|
4. **Changelog sync**: Tag after CHANGELOG update
|
|
5. **CI/CD integration**: Automate tag creation in pipeline
|
|
|
|
## ⚠️ Troubleshooting
|
|
|
|
### Version Not Updating
|
|
|
|
**Problem**: Version shows old value after bump
|
|
|
|
**Solution**:
|
|
```bash
|
|
# 1. Check VERSION file
|
|
cat VERSION
|
|
|
|
# 2. Rebuild binary
|
|
./scripts/build-with-version.sh
|
|
|
|
# 3. Restart server
|
|
./scripts/start-server.sh restart
|
|
```
|
|
|
|
### Swagger Docs Missing Endpoints
|
|
|
|
**Problem**: Greet endpoints missing from Swagger UI
|
|
|
|
**Solution**:
|
|
```bash
|
|
# Regenerate docs from project root
|
|
swag init -g ./cmd/server/main.go --parseDependency --parseInternal
|
|
|
|
# Move docs to correct location
|
|
mv docs/* pkg/server/docs/
|
|
|
|
# Restart server
|
|
./scripts/start-server.sh restart
|
|
```
|
|
|
|
### Git Tag Issues
|
|
|
|
**Problem**: Tag push rejected
|
|
|
|
**Solution**:
|
|
```bash
|
|
# Delete local tag
|
|
git tag -d v1.0.1
|
|
|
|
# Delete remote tag
|
|
git push origin :refs/tags/v1.0.1
|
|
|
|
# Recreate tag
|
|
git tag -a v1.0.1 -m "Release 1.0.1"
|
|
git push origin v1.0.1
|
|
```
|
|
|
|
## 📚 Resources
|
|
|
|
- [Semantic Versioning](https://semver.org/)
|
|
- [Keep a Changelog](https://keepachangelog.com/)
|
|
- [Conventional Commits](https://www.conventionalcommits.org/)
|
|
- [Git Tagging](https://git-scm.com/book/en/v2/Git-Basics-Tagging)
|
|
|
|
---
|
|
|
|
**Maintained by:** dance-lessons-coach Team
|
|
**Last Updated:** 2026-04-05
|
|
**Version:** 1.0 |