Add comprehensive versioning documentation
Documents: - Semantic versioning workflow - How to bump versions with script - CI/CD pipeline behavior - Version checking at startup and hourly - Docker Hub tagging strategy - Best practices for when to bump - Troubleshooting guide - Development tips
This commit is contained in:
parent
097c4bd581
commit
831588e97d
1 changed files with 211 additions and 0 deletions
211
VERSIONING.md
Normal file
211
VERSIONING.md
Normal file
|
|
@ -0,0 +1,211 @@
|
|||
# Agent Versioning
|
||||
|
||||
The towerops-agent uses **semantic versioning** (semver) to track releases and enable automatic update detection.
|
||||
|
||||
## Version Format
|
||||
|
||||
Versions follow the format: `MAJOR.MINOR.PATCH`
|
||||
|
||||
- **MAJOR**: Breaking changes (API incompatibility)
|
||||
- **MINOR**: New features (backwards compatible)
|
||||
- **PATCH**: Bug fixes (backwards compatible)
|
||||
|
||||
## Current Version
|
||||
|
||||
The version is defined in `Cargo.toml`:
|
||||
|
||||
```toml
|
||||
[package]
|
||||
version = "0.1.0"
|
||||
```
|
||||
|
||||
This is the **source of truth** for the agent's version.
|
||||
|
||||
## Bumping Versions
|
||||
|
||||
Use the provided script to increment the version:
|
||||
|
||||
```bash
|
||||
# Patch release (0.1.0 -> 0.1.1) - bug fixes
|
||||
./scripts/bump-version.sh patch
|
||||
|
||||
# Minor release (0.1.0 -> 0.2.0) - new features
|
||||
./scripts/bump-version.sh minor
|
||||
|
||||
# Major release (0.1.0 -> 1.0.0) - breaking changes
|
||||
./scripts/bump-version.sh major
|
||||
```
|
||||
|
||||
The script will:
|
||||
1. ✅ Update `Cargo.toml` with new version
|
||||
2. ✅ Update `Cargo.lock`
|
||||
3. ✅ Create git commit
|
||||
4. ✅ Create git tag (e.g., `v0.1.1`)
|
||||
|
||||
Then push:
|
||||
```bash
|
||||
git push origin main
|
||||
git push origin v0.1.1 # Push the tag
|
||||
```
|
||||
|
||||
## CI/CD Pipeline
|
||||
|
||||
When you push to main or push a tag, GitLab CI automatically:
|
||||
|
||||
### On Main Branch Push
|
||||
- Builds Docker image for `linux/amd64`
|
||||
- Extracts version from `Cargo.toml`
|
||||
- Tags image with:
|
||||
- `:latest` (always)
|
||||
- `:0.1.0` (version from Cargo.toml)
|
||||
- `:main-abc123` (commit SHA)
|
||||
- Pushes to Docker Hub
|
||||
|
||||
### On Git Tag Push (e.g., `v0.1.0`)
|
||||
- Builds multi-arch Docker image (`linux/amd64`, `linux/arm64`)
|
||||
- Tags image with:
|
||||
- `:0.1.0` (extracted from tag)
|
||||
- `:v0.1.0` (original tag name)
|
||||
- `:latest` (always)
|
||||
- Pushes to Docker Hub
|
||||
|
||||
## Version Checking
|
||||
|
||||
The agent checks Docker Hub for newer versions:
|
||||
|
||||
### At Startup
|
||||
```
|
||||
[INFO] Current version: 0.1.0
|
||||
[INFO] ✓ Running latest version (0.1.0)
|
||||
```
|
||||
|
||||
Or if outdated:
|
||||
```
|
||||
[INFO] Current version: 0.1.0
|
||||
[WARN] ⚠️ Newer version available: 0.2.0 (current: 0.1.0)
|
||||
[WARN] Automatic updates will pull new version every hour
|
||||
```
|
||||
|
||||
### Every Hour
|
||||
The agent checks Docker Hub for newer semver tags and automatically pulls if a newer version is available.
|
||||
|
||||
## How It Works
|
||||
|
||||
1. **Agent queries Docker Hub**: `GET /v2/repositories/gmcintire/towerops-agent/tags?page_size=100`
|
||||
2. **Filters for semver tags**: Only considers tags matching `X.Y.Z` format
|
||||
3. **Compares versions**: Uses semver comparison (`0.2.0` > `0.1.0`)
|
||||
4. **Pulls if newer**: If newer version exists, runs `docker pull gmcintire/towerops-agent:latest`
|
||||
5. **Restarts**: Exits with code 0, docker-compose/k8s restarts with new image
|
||||
|
||||
## Docker Hub Tags
|
||||
|
||||
After a few releases, you'll see:
|
||||
|
||||
```
|
||||
gmcintire/towerops-agent:latest # Always newest
|
||||
gmcintire/towerops-agent:0.2.0 # Specific version
|
||||
gmcintire/towerops-agent:0.1.1 # Previous version
|
||||
gmcintire/towerops-agent:0.1.0 # Original version
|
||||
gmcintire/towerops-agent:main-abc123 # Commit SHA (transient)
|
||||
```
|
||||
|
||||
## Version History
|
||||
|
||||
### 0.1.0 (Initial Release)
|
||||
- SNMP polling with sensors and interfaces
|
||||
- Protocol Buffers API communication
|
||||
- SQLite buffering with 24h retention
|
||||
- Automatic Docker self-updates
|
||||
- Health endpoint on port 8080
|
||||
|
||||
## Best Practices
|
||||
|
||||
### When to Bump
|
||||
|
||||
- **Patch** (0.1.0 → 0.1.1)
|
||||
- Bug fixes
|
||||
- Performance improvements
|
||||
- Documentation updates
|
||||
- Internal refactoring
|
||||
|
||||
- **Minor** (0.1.0 → 0.2.0)
|
||||
- New SNMP OID support
|
||||
- New metric types
|
||||
- New configuration options
|
||||
- New features (backwards compatible)
|
||||
|
||||
- **Major** (0.1.0 → 1.0.0)
|
||||
- Protocol Buffers schema changes (breaking)
|
||||
- Configuration format changes
|
||||
- API endpoint changes
|
||||
- Removal of deprecated features
|
||||
|
||||
### Release Checklist
|
||||
|
||||
Before bumping version:
|
||||
|
||||
- [ ] All tests passing: `cargo test`
|
||||
- [ ] No clippy warnings: `cargo clippy`
|
||||
- [ ] Code formatted: `cargo fmt`
|
||||
- [ ] CHANGELOG.md updated (if exists)
|
||||
- [ ] Breaking changes documented
|
||||
- [ ] Migration guide written (for major versions)
|
||||
|
||||
### Rolling Back
|
||||
|
||||
If you need to roll back to a previous version:
|
||||
|
||||
```bash
|
||||
# Update docker-compose.yml to pin specific version
|
||||
services:
|
||||
towerops-agent:
|
||||
image: gmcintire/towerops-agent:0.1.0 # Pin to specific version
|
||||
```
|
||||
|
||||
Or via environment variable:
|
||||
```bash
|
||||
AGENT_VERSION=0.1.0 docker-compose up -d
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "No valid semver tags found"
|
||||
- No version tags exist on Docker Hub yet
|
||||
- Push a version tag: `./scripts/bump-version.sh patch && git push --tags`
|
||||
|
||||
### "Could not check for updates"
|
||||
- Docker Hub API unreachable
|
||||
- Network connectivity issue
|
||||
- Agent continues to run normally
|
||||
|
||||
### Auto-update not working
|
||||
- Check Docker socket is mounted: `-v /var/run/docker.sock:/var/run/docker.sock`
|
||||
- Check container has permissions: `docker logs <container>`
|
||||
- Verify using `:latest` tag, not pinned version
|
||||
|
||||
### Agent always pulling but not restarting
|
||||
- `docker pull` succeeds but shows "Image is up to date"
|
||||
- This is correct behavior - only restarts if new image downloaded
|
||||
- Agent is already running the latest version
|
||||
|
||||
## Development
|
||||
|
||||
During development, disable auto-updates by running without Docker socket:
|
||||
|
||||
```bash
|
||||
cargo run -- \
|
||||
--api-url http://localhost:4000 \
|
||||
--token <token>
|
||||
```
|
||||
|
||||
Or run in Docker without socket mount:
|
||||
```yaml
|
||||
services:
|
||||
towerops-agent:
|
||||
image: gmcintire/towerops-agent:latest
|
||||
# Don't mount socket during dev
|
||||
# volumes:
|
||||
# - /var/run/docker.sock:/var/run/docker.sock
|
||||
```
|
||||
|
||||
This prevents auto-updates during development/testing.
|
||||
Loading…
Add table
Reference in a new issue