📁 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:
228
documentation/BDD_GUIDE.md
Normal file
228
documentation/BDD_GUIDE.md
Normal file
@@ -0,0 +1,228 @@
|
||||
# BDD Testing Guide for DanceLessonsCoach
|
||||
|
||||
This guide explains how to work with BDD tests using Godog in the DanceLessonsCoach project.
|
||||
|
||||
## Installation
|
||||
|
||||
### Modern Go Approach (Recommended)
|
||||
|
||||
The idiomatic and modern way to install Godog for developers joining the project:
|
||||
|
||||
```bash
|
||||
# Install Godog as a Go tool (recommended approach)
|
||||
go install github.com/cucumber/godog/cmd/godog@latest
|
||||
```
|
||||
|
||||
This installs the `godog` binary in your `$GOPATH/bin` directory. Make sure this directory is in your `PATH`.
|
||||
|
||||
### Alternative: Using go run
|
||||
|
||||
You can also run Godog directly without installing:
|
||||
|
||||
```bash
|
||||
go run github.com/cucumber/godog/cmd/godog@latest
|
||||
```
|
||||
|
||||
### Project Setup
|
||||
|
||||
The project already includes Godog as a dependency in `go.mod`. The BDD tests are integrated into the standard Go testing framework.
|
||||
|
||||
## Running BDD Tests
|
||||
|
||||
### Run All BDD Tests
|
||||
|
||||
```bash
|
||||
# From project root
|
||||
cd /Users/gabrielradureau/Work/Vibe/DanceLessonsCoach
|
||||
go test ./features/... -v
|
||||
```
|
||||
|
||||
### Run Specific Feature
|
||||
|
||||
```bash
|
||||
# Run only greet feature
|
||||
go test ./features/... -v -run "TestBDD/Greet"
|
||||
|
||||
# Run only health feature
|
||||
go test ./features/... -v -run "TestBDD/Health"
|
||||
|
||||
# Run only readiness feature
|
||||
go test ./features/... -v -run "TestBDD/Readiness"
|
||||
```
|
||||
|
||||
### Different Output Formats
|
||||
|
||||
```bash
|
||||
# Progress format (default)
|
||||
go test ./features/... -v
|
||||
|
||||
# Pretty format
|
||||
go test ./features/... -v -godog.format=pretty
|
||||
|
||||
# JSON format
|
||||
go test ./features/... -v -godog.format=json
|
||||
|
||||
# HTML report
|
||||
go test ./features/... -v -godog.format=html > report.html
|
||||
```
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
features/
|
||||
├── bdd_test.go # Main test entry point
|
||||
├── greet.feature # Greet service feature
|
||||
└── health.feature # Health endpoint feature
|
||||
|
||||
pkg/bdd/
|
||||
├── steps/ # Step definitions
|
||||
│ └── steps.go # All step definitions
|
||||
│
|
||||
├── testserver/ # Test infrastructure
|
||||
│ ├── server.go # Test server management
|
||||
│ └── client.go # HTTP client for testing
|
||||
│
|
||||
├── suite.go # Test suite initialization
|
||||
└── README.md # BDD usage guide
|
||||
```
|
||||
|
||||
## Writing New Features
|
||||
|
||||
### 1. Create Feature File
|
||||
|
||||
Create a new `.feature` file in the `features/` directory using Gherkin syntax:
|
||||
|
||||
```gherkin
|
||||
# features/new_feature.feature
|
||||
Feature: New Feature
|
||||
Description of the new feature
|
||||
|
||||
Scenario: Happy path
|
||||
Given some precondition
|
||||
When I perform an action
|
||||
Then I should see the expected result
|
||||
```
|
||||
|
||||
### 2. Implement Step Definitions
|
||||
|
||||
Create a corresponding step definition file in `pkg/bdd/steps/`:
|
||||
|
||||
```go
|
||||
// pkg/bdd/steps/new_feature_steps.go
|
||||
package steps
|
||||
|
||||
import (
|
||||
"DanceLessonsCoach/pkg/bdd/testserver"
|
||||
"github.com/cucumber/godog"
|
||||
)
|
||||
|
||||
func InitializeNewFeatureSteps(ctx *godog.ScenarioContext, client *testserver.Client) {
|
||||
ctx.Step(`^some precondition$`, func() error {
|
||||
// Implementation
|
||||
return nil
|
||||
})
|
||||
|
||||
ctx.Step(`^I perform an action$`, func() error {
|
||||
// Implementation
|
||||
return nil
|
||||
})
|
||||
|
||||
ctx.Step(`^I should see the expected result$`, func() error {
|
||||
// Implementation
|
||||
return nil
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Register Steps
|
||||
|
||||
Add your step initialization to `pkg/bdd/suite.go`:
|
||||
|
||||
```go
|
||||
func InitializeScenario(ctx *godog.ScenarioContext) {
|
||||
server := testserver.NewServer()
|
||||
client := testserver.NewClient(server)
|
||||
|
||||
// Initialize all steps using the unified approach
|
||||
steps.InitializeAllSteps(ctx, client)
|
||||
|
||||
// ... cleanup code
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Test Organization
|
||||
|
||||
- **One feature per file**: Keep feature files focused on a single capability
|
||||
- **Clear scenario names**: Use descriptive scenario names that explain the behavior
|
||||
- **Reusable steps**: Create reusable step definitions when possible
|
||||
- **Black box testing**: Test through public APIs only, no internal knowledge
|
||||
|
||||
### Performance
|
||||
|
||||
- **Parallel execution**: Godog supports parallel scenario execution
|
||||
- **Isolated scenarios**: Each scenario should be independent
|
||||
- **Cleanup**: Always cleanup resources in `After` hooks
|
||||
|
||||
### Debugging
|
||||
|
||||
- **Verbose output**: Use `-v` flag for detailed output
|
||||
- **Step-by-step**: Run with `-godog.tags=@focus` to run specific scenarios
|
||||
- **Dry run**: Check step definitions without running tests
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Server not starting
|
||||
|
||||
If tests fail with "server did not become ready", check:
|
||||
- Port conflicts: `lsof -i :8080`
|
||||
- Server logs: Check if server process starts properly
|
||||
- Configuration: Verify config.yaml settings
|
||||
|
||||
### Missing step definitions
|
||||
|
||||
If you see "undefined steps", you need to:
|
||||
1. Implement the missing step definitions
|
||||
2. Register them in the suite initialization
|
||||
3. Re-run the tests
|
||||
|
||||
### Test isolation issues
|
||||
|
||||
Ensure each scenario:
|
||||
- Starts with a clean state
|
||||
- Doesn't depend on other scenarios
|
||||
- Properly cleans up resources
|
||||
|
||||
## CI/CD Integration
|
||||
|
||||
Add BDD tests to your CI pipeline:
|
||||
|
||||
```yaml
|
||||
# Example GitHub Actions step
|
||||
- name: Run BDD Tests
|
||||
run: go test ./features/... -v
|
||||
```
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Godog GitHub](https://github.com/cucumber/godog)
|
||||
- [Godog Documentation](https://github.com/cucumber/godog#readme)
|
||||
- [Cucumber Documentation](https://cucumber.io/docs/gherkin/)
|
||||
- [BDD Introduction](https://dannorth.net/introducing-bdd/)
|
||||
|
||||
## Modern Go Testing Practices
|
||||
|
||||
The DanceLessonsCoach project follows modern Go testing practices:
|
||||
|
||||
1. **Standard library integration**: BDD tests use `go test`
|
||||
2. **No global installation required**: Godog is a Go module dependency
|
||||
3. **Cross-platform**: Works on all Go-supported platforms
|
||||
4. **IDE integration**: Works with Go tools and IDEs
|
||||
5. **Dependency management**: Versioned through go.mod
|
||||
|
||||
This approach ensures that:
|
||||
- All developers use the same Godog version
|
||||
- No manual installation steps are needed
|
||||
- Tests work consistently across environments
|
||||
- CI/CD integration is straightforward
|
||||
305
documentation/local-ci-cd-testing.md
Normal file
305
documentation/local-ci-cd-testing.md
Normal file
@@ -0,0 +1,305 @@
|
||||
# Local CI/CD Testing Guide
|
||||
|
||||
This guide explains how to test the CI/CD pipeline locally without requiring a Gitea instance.
|
||||
|
||||
## Overview
|
||||
|
||||
The local CI/CD testing allows you to:
|
||||
- Test the entire build process locally
|
||||
- Simulate version bumping based on commit conventions
|
||||
- Build Docker images with the correct version tags
|
||||
- Test the container before pushing to production
|
||||
|
||||
## Available Testing Methods
|
||||
|
||||
### 1. Interactive Local Testing Script
|
||||
|
||||
**File:** `scripts/test-local-ci-cd.sh`
|
||||
|
||||
**What it does:**
|
||||
- Installs dependencies
|
||||
- Generates Swagger documentation
|
||||
- Runs compilation and tests
|
||||
- Builds binaries
|
||||
- Simulates version bumping
|
||||
- Provides Docker build instructions
|
||||
- Optionally builds and runs Docker container
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
./scripts/test-local-ci-cd.sh
|
||||
```
|
||||
|
||||
**Features:**
|
||||
- Interactive prompts for Docker build and run
|
||||
- Automatic endpoint testing
|
||||
- Clear instructions for each step
|
||||
- Version-aware Docker image tagging
|
||||
|
||||
### 2. Local CI/CD Workflow
|
||||
|
||||
**File:** `.gitea/workflows/test-local-ci-cd.yaml`
|
||||
|
||||
**What it does:**
|
||||
- Simulates the CI/CD pipeline in a workflow format
|
||||
- Provides detailed instructions for local Docker builds
|
||||
- Shows version bump simulation
|
||||
- Lists all test results
|
||||
|
||||
**Usage:**
|
||||
This workflow can be triggered manually or on test/feature branches.
|
||||
|
||||
### 3. Workflow Validation
|
||||
|
||||
**File:** `scripts/cicd/validate-workflow.sh`
|
||||
|
||||
**What it does:**
|
||||
- Validates YAML syntax
|
||||
- Checks required workflow fields
|
||||
- Validates job structure
|
||||
- Verifies Arcodange-specific configurations
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
./scripts/cicd/validate-workflow.sh
|
||||
```
|
||||
|
||||
## Step-by-Step Local Testing
|
||||
|
||||
### 1. Run the Interactive Script
|
||||
|
||||
```bash
|
||||
cd /Users/gabrielradureau/Work/Vibe/DanceLessonsCoach
|
||||
./scripts/test-local-ci-cd.sh
|
||||
```
|
||||
|
||||
### 2. Follow the Prompts
|
||||
|
||||
The script will guide you through:
|
||||
- Environment setup
|
||||
- Dependency installation
|
||||
- Code compilation and testing
|
||||
- Binary building
|
||||
- Version bump simulation
|
||||
- Docker build options
|
||||
|
||||
### 3. Docker Testing (Optional)
|
||||
|
||||
If you choose to build the Docker image:
|
||||
|
||||
```bash
|
||||
# Build with current version
|
||||
docker build -t dance-lessons-coach:$CURRENT_VERSION .
|
||||
|
||||
# Tag as latest
|
||||
docker tag dance-lessons-coach:$CURRENT_VERSION dance-lessons-coach:latest
|
||||
|
||||
# Check if port is available
|
||||
./scripts/check-port.sh 8080 8081 8082
|
||||
|
||||
# Run the container (use available port)
|
||||
docker run -d -p 8080:8080 --name dance-lessons-coach-test dance-lessons-coach:$CURRENT_VERSION
|
||||
# Or use alternative port if 8080 is in use
|
||||
docker run -d -p 8081:8080 --name dance-lessons-coach-test dance-lessons-coach:$CURRENT_VERSION
|
||||
|
||||
# Branch-specific naming (recommended for multiple branches)
|
||||
BRANCH=$(git rev-parse --abbrev-ref HEAD | tr '/' '-')
|
||||
docker run -d -p 8080:8080 --name "dance-lessons-coach-$BRANCH" dance-lessons-coach:$CURRENT_VERSION
|
||||
```
|
||||
|
||||
**Port Checking:**
|
||||
The script automatically checks if port 8080 is available and suggests alternatives.
|
||||
|
||||
**Container Management:**
|
||||
- Automatically removes existing containers with the same name
|
||||
- Uses branch-based naming to avoid conflicts
|
||||
- Supports multiple branch testing simultaneously
|
||||
|
||||
### 4. Test the Container
|
||||
|
||||
```bash
|
||||
# Health check
|
||||
curl http://localhost:8080/api/health
|
||||
|
||||
# Greet endpoint
|
||||
curl http://localhost:8080/api/v1/greet/YourName
|
||||
|
||||
# Swagger UI
|
||||
open http://localhost:8080/swagger/
|
||||
```
|
||||
|
||||
### 5. Clean Up
|
||||
|
||||
```bash
|
||||
# Stop and remove container (generic)
|
||||
docker stop dance-lessons-coach-test
|
||||
docker rm dance-lessons-coach-test
|
||||
|
||||
# Stop and remove branch-specific container
|
||||
BRANCH=$(git rev-parse --abbrev-ref HEAD | tr '/' '-')
|
||||
docker stop "dance-lessons-coach-$BRANCH"
|
||||
docker rm "dance-lessons-coach-$BRANCH"
|
||||
|
||||
# Remove all test containers
|
||||
docker stop $(docker ps -aq --filter "name=dance-lessons-coach")
|
||||
docker rm $(docker ps -aq --filter "name=dance-lessons-coach")
|
||||
|
||||
# Remove images (optional)
|
||||
docker rmi dance-lessons-coach:$CURRENT_VERSION
|
||||
docker rmi dance-lessons-coach:latest
|
||||
```
|
||||
|
||||
**Cleanup Tips:**
|
||||
- Use `docker ps -a` to see all containers
|
||||
- Use `docker images` to see all images
|
||||
- Use `docker system prune` to clean up unused objects
|
||||
|
||||
## Version Management
|
||||
|
||||
The local testing respects the same version conventions as the production CI/CD:
|
||||
|
||||
- **feat:** commits → MINOR version bump
|
||||
- **fix:** commits → PATCH version bump
|
||||
- **BREAKING CHANGE:** → MAJOR version bump
|
||||
- Other commits → No automatic bump
|
||||
|
||||
**Manual version bump:**
|
||||
```bash
|
||||
# Bump patch version
|
||||
./scripts/version-bump.sh patch
|
||||
|
||||
# Bump minor version
|
||||
./scripts/version-bump.sh minor
|
||||
|
||||
# Bump major version
|
||||
./scripts/version-bump.sh major
|
||||
```
|
||||
|
||||
## Docker Build Optimization
|
||||
|
||||
The Dockerfile is optimized to:
|
||||
- Only install swag if swagger.json doesn't exist
|
||||
- Reuse existing swagger.json from CI/CD workflow
|
||||
- Generate documentation only when needed
|
||||
|
||||
This means:
|
||||
- **Local builds:** Will generate swagger docs if missing
|
||||
- **CI/CD builds:** Will reuse existing swagger.json
|
||||
- **Production builds:** Most efficient path
|
||||
|
||||
## Testing Different Scenarios
|
||||
|
||||
### Test Version Bumping
|
||||
|
||||
```bash
|
||||
# Make a feature commit
|
||||
git commit -m "feat: add new feature"
|
||||
./scripts/test-local-ci-cd.sh # Will show MINOR bump suggestion
|
||||
|
||||
# Make a fix commit
|
||||
git commit -m "fix: resolve issue"
|
||||
./scripts/test-local-ci-cd.sh # Will show PATCH bump suggestion
|
||||
```
|
||||
|
||||
### Test Without Docker
|
||||
|
||||
```bash
|
||||
# Run tests without Docker
|
||||
./scripts/test-local-ci-cd.sh
|
||||
# Answer 'n' when asked about Docker build
|
||||
```
|
||||
|
||||
### Test Specific Components
|
||||
|
||||
```bash
|
||||
# Just build and test
|
||||
go build ./...
|
||||
go test ./... -cover
|
||||
|
||||
# Just generate swagger docs
|
||||
cd pkg/server && go generate
|
||||
|
||||
# Just build binaries
|
||||
./scripts/build.sh
|
||||
|
||||
# Check port availability
|
||||
./scripts/check-port.sh 8080 8081 8082
|
||||
```
|
||||
|
||||
## Production Deployment
|
||||
|
||||
When you're ready to deploy:
|
||||
|
||||
1. **Commit your changes** with appropriate commit message
|
||||
2. **Push to main branch** to trigger production CI/CD
|
||||
3. **Monitor the workflow** in Gitea Actions
|
||||
4. **Verify the Docker image** in Gitea Container Registry
|
||||
|
||||
```bash
|
||||
# Example production deployment
|
||||
git add .
|
||||
git commit -m "feat: add new API endpoint"
|
||||
git push origin main
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Port Conflicts
|
||||
|
||||
```bash
|
||||
# Check what's using port 8080
|
||||
./scripts/check-port.sh 8080
|
||||
|
||||
# Find and kill process on port 8080
|
||||
kill -9 $(lsof -ti :8080)
|
||||
|
||||
# Use alternative port
|
||||
docker run -d -p 8081:8080 --name dance-lessons-coach-test dance-lessons-coach:$CURRENT_VERSION
|
||||
```
|
||||
|
||||
### Docker Build Issues
|
||||
|
||||
```bash
|
||||
# Clean build
|
||||
docker system prune -a --volumes
|
||||
rm -rf pkg/server/docs/
|
||||
./scripts/test-local-ci-cd.sh
|
||||
```
|
||||
|
||||
### Dependency Issues
|
||||
|
||||
```bash
|
||||
# Clean and reinstall
|
||||
go clean -cache
|
||||
go mod tidy
|
||||
./scripts/test-local-ci-cd.sh
|
||||
```
|
||||
|
||||
### Test Failures
|
||||
|
||||
```bash
|
||||
# Run specific test
|
||||
go test ./pkg/greet/ -v
|
||||
|
||||
# Run with race detector
|
||||
go test ./... -race
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Test locally first** before pushing to CI/CD
|
||||
2. **Use commit conventions** for automatic version bumping
|
||||
3. **Test Docker images** before production deployment
|
||||
4. **Clean up containers** after testing
|
||||
5. **Monitor CI/CD logs** for any issues
|
||||
|
||||
## Summary
|
||||
|
||||
The local CI/CD testing provides:
|
||||
- ✅ Full build pipeline simulation
|
||||
- ✅ Version-aware Docker builds
|
||||
- ✅ Interactive testing experience
|
||||
- ✅ Production-like environment
|
||||
- ✅ Easy troubleshooting
|
||||
|
||||
Use these tools to ensure your changes work correctly before deploying to production!
|
||||
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