📁 refactor: consolidate doc/ into documentation/ directory
Some checks failed
CI/CD Pipeline / CI Pipeline (push) Has been cancelled
Some checks failed
CI/CD Pipeline / CI Pipeline (push) Has been cancelled
- Moved all documentation files from doc/ to documentation/ - Removed empty doc/ directory - Single unified location for all project documentation - Includes BDD guide, CI/CD testing guide, version management guide Refs: #documentation, #organization, #cleanup
This commit is contained in:
365
documentation/version-management-guide.md
Normal file
365
documentation/version-management-guide.md
Normal file
@@ -0,0 +1,365 @@
|
||||
# Version Management Guide
|
||||
|
||||
This guide provides comprehensive instructions for managing versions in the DanceLessonsCoach 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
|
||||
|
||||
DanceLessonsCoach 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:** DanceLessonsCoach Team
|
||||
**Last Updated:** 2026-04-05
|
||||
**Version:** 1.0
|
||||
Reference in New Issue
Block a user