# Semantic Versioning Quick Reference
## TL;DR
```bash
# Bug fix
./scripts/bump_version.sh patch # 0.4.0 → 0.4.1
# New feature
./scripts/bump_version.sh minor # 0.4.0 → 0.5.0
# Breaking change
./scripts/bump_version.sh major # 0.4.0 → 1.0.0
# Pre-release
./scripts/bump_version.sh minor --pre-release alpha # 0.4.0 → 0.5.0-alpha.1
```
## When to Bump What
### MAJOR (X.0.0) - Breaking Changes
**Breaking = Existing code stops working**
- ❌ Removing MCP tools
- ❌ Changing tool signatures (removing parameters)
- ❌ Removing required state fields
- ❌ Changing configuration format
- ❌ Breaking protocol changes
**Example:**
```python
# v0.4.0
def update_state(summary, next_steps, active_files, ask_user=False):
pass
# v1.0.0 - BREAKING: removed ask_user parameter
def update_state(summary, next_steps, active_files):
pass
```
### MINOR (0.X.0) - New Features
**New = Adds functionality without breaking existing code**
- ✅ Adding new MCP tools
- ✅ Adding optional parameters
- ✅ Adding new state fields (optional)
- ✅ Adding new configuration options
- ✅ New backwards-compatible features
**Example:**
```python
# v0.4.0
# Tools: update_state, add_task, read_state (10 tools)
# v0.5.0 - NEW: Added 3 tools (backwards compatible)
# Tools: update_state, add_task, read_state, set_agent_status, claim_best_task, assess_workload (13 tools)
```
### PATCH (0.0.X) - Bug Fixes
**Fix = Corrects incorrect behavior**
- 🐛 Bug fixes
- 🐛 Performance improvements (no API change)
- 🐛 Documentation fixes
- 🐛 Internal refactoring
- 🐛 Dependency updates (patch versions only)
**Example:**
```python
# v0.4.0 - Bug: race condition in file locking
def write_with_lock(file, data):
# Broken: no timeout
lock.acquire()
# v0.4.1 - Fixed: added timeout
def write_with_lock(file, data):
# Fixed: with timeout
lock.acquire(timeout=10)
```
## Quick Decision Tree
```
Does it break existing functionality?
├─ YES → MAJOR (1.0.0)
└─ NO
│
Does it add new features?
├─ YES → MINOR (0.5.0)
└─ NO
│
Does it fix bugs?
├─ YES → PATCH (0.4.1)
└─ NO → Documentation only (no bump)
```
## Common Scenarios
### Scenario 1: Adding a New Tool
**Change:** Added `assess_workload()` tool
**Decision:** MINOR (new feature, backwards compatible)
**Reason:** Existing code continues to work, new tool is optional
```bash
./scripts/bump_version.sh minor # 0.4.0 → 0.5.0
```
### Scenario 2: Fixing a Bug
**Change:** Fixed race condition in heartbeat monitor
**Decision:** PATCH (bug fix)
**Reason:** Corrects incorrect behavior, doesn't add features
```bash
./scripts/bump_version.sh patch # 0.4.0 → 0.4.1
```
### Scenario 3: Removing a Tool
**Change:** Removed deprecated `old_claim_task()` tool
**Decision:** MAJOR (breaking change)
**Reason:** Existing code using this tool will break
```bash
./scripts/bump_version.sh major # 0.4.0 → 1.0.0
```
### Scenario 4: Adding Optional Parameter
**Change:** Added optional `priority` parameter to `add_task()`
**Decision:** MINOR (new feature, backwards compatible)
**Reason:** Existing calls work (default value), new calls can use it
```bash
./scripts/bump_version.sh minor # 0.4.0 → 0.5.0
```
### Scenario 5: Changing Required Parameter Type
**Change:** Changed `next_steps` from `List[str]` to `List[Dict]`
**Decision:** MAJOR (breaking change)
**Reason:** Existing code passing strings will break
```bash
./scripts/bump_version.sh major # 0.4.0 → 1.0.0
```
## Pre-Release Versions
Use for testing before official release:
```bash
# Alpha - early testing
./scripts/bump_version.sh minor --pre-release alpha
# 0.4.0 → 0.5.0-alpha.1
# Subsequent alphas
./scripts/bump_version.sh minor --pre-release alpha
# 0.5.0-alpha.1 → 0.5.0-alpha.2
# Beta - feature complete
./scripts/bump_version.sh minor --pre-release beta
# 0.5.0-alpha.2 → 0.5.0-beta.1
# Release candidate
./scripts/bump_version.sh minor --pre-release rc
# 0.5.0-beta.1 → 0.5.0-rc.1
# Final release
./scripts/bump_version.sh minor
# 0.5.0-rc.1 → 0.5.0
```
## Version Release Workflow
### 1. Decide Version Bump
```bash
# Use the decision tree above
# Bug fix? → patch
# New feature? → minor
# Breaking change? → major
```
### 2. Bump Version
```bash
./scripts/bump_version.sh [major|minor|patch]
```
### 3. Validate Version
```bash
./scripts/validate_version.sh
```
### 4. Update CHANGELOG
Edit `CHANGELOG.md`:
```markdown
## [0.5.0] - 2026-02-02
### Added
- New assess_workload() tool for cluster intelligence
- Workload-based spawn recommendations
### Fixed
- Race condition in heartbeat monitor
```
### 5. Validate Everything
```bash
./scripts/validate_before_install.sh
```
### 6. Commit and Tag
```bash
git add pyproject.toml src/amicus/__init__.py CHANGELOG.md
git commit -m "chore: bump version to 0.5.0"
git tag -a v0.5.0 -m "Release v0.5.0"
```
### 7. Push
```bash
git push origin main
git push origin v0.5.0
```
## Breaking Change Policy
### If You MUST Make a Breaking Change
**Step 1: Deprecate (MINOR version)**
```python
# v0.5.0
@mcp.tool()
def old_function(param):
warnings.warn("old_function is deprecated, use new_function", DeprecationWarning)
# Still works but warns
@mcp.tool()
def new_function(param):
# New implementation
```
**Step 2: Document (in CHANGELOG)**
```markdown
## [0.5.0] - YYYY-MM-DD
### Deprecated
- `old_function` - Use `new_function` instead. Will be removed in v1.0.0
### Migration Guide
Replace all calls to `old_function(x)` with `new_function(x)`.
```
**Step 3: Remove (MAJOR version, at least one MINOR later)**
```python
# v1.0.0
# old_function removed
@mcp.tool()
def new_function(param):
# Only new implementation
```
## Validation Commands
### Check Version Consistency
```bash
./scripts/validate_version.sh
```
Checks:
- ✓ pyproject.toml version
- ✓ __init__.py version
- ✓ CLI --version output
- ✓ Versions match
- ✓ SemVer format valid
- ✓ Git tag status
- ✓ CHANGELOG entry exists
### Check Installation
```bash
amicus-mcp --version
# Should match pyproject.toml
amicus-mcp --list-tools | wc -l
# Should be 15+ tools
```
## Common Mistakes
### ❌ Wrong: Patch bump for new feature
```bash
# Added new tool, used patch
./scripts/bump_version.sh patch # WRONG
# 0.4.0 → 0.4.1
```
**Correct:**
```bash
./scripts/bump_version.sh minor
# 0.4.0 → 0.5.0
```
### ❌ Wrong: Minor bump for breaking change
```bash
# Removed tool, used minor
./scripts/bump_version.sh minor # WRONG
# 0.4.0 → 0.5.0
```
**Correct:**
```bash
./scripts/bump_version.sh major
# 0.4.0 → 1.0.0
```
### ❌ Wrong: No deprecation before removal
```python
# v0.5.0 - had old_function
# v0.6.0 - removed old_function # WRONG: No warning
```
**Correct:**
```python
# v0.5.0 - deprecate old_function with warning
# v0.6.0 - still have old_function with warning
# v1.0.0 - remove old_function (MAJOR bump)
```
## Version History Reference
- **v0.4.0** - Anti-idle system, validation, governance
- **v0.3.0** - Self-managing cluster protocol
- **v0.2.0** - CLI commands, audit framework
- **v0.1.0** - Initial release, core MCP tools
## Additional Resources
- [Semantic Versioning 2.0.0](https://semver.org/)
- [Keep a Changelog](https://keepachangelog.com/)
- [GOVERNANCE.md](../GOVERNANCE.md) - Full versioning policy
- [CHANGELOG.md](../CHANGELOG.md) - Version history
---
**Remember**: When in doubt, bump more conservatively (patch → minor, minor → major). It's easier to under-promise and over-deliver than the reverse.
