# Version Management - Release Workflow

## ⚠️ CRITICAL: Always Use github-release-manager Agent

**NEVER do manual releases** (major, minor, patch, or hotfixes). Manual workflows miss steps and are error-prone.

## Release Branch Workflow (Adopted 2026-01-27)

```
feature-branches → main (development)
                      ↓
              release/vX.Y.Z (preparation)
                      ↓
                  tag vX.Y.Z
                      ↓
              merge back to main
```

### Workflow Steps:

1. **Development**: All feature/fix branches merge to `main`
2. **Release Preparation**: Create `release/vX.Y.Z` branch from `main`
3. **Version Bump**: Update version files on release branch
4. **PR & Merge**: Create PR, merge with `--admin --squash`
5. **Tag**: Create annotated tag `vX.Y.Z`
6. **GitHub Release**: Create release from tag
7. **Sync**: Release branch auto-deleted, main stays current

### Benefits:
- `main` = active development (current work)
- Release branches only when needed
- No permanent `develop` branch to maintain
- Clear separation of release preparation

## Five-File Version Bump Procedure

1. Update `src/mcp_memory_service/_version.py` (`__version__ = "X.Y.Z"`)
2. Update `pyproject.toml` (line ~7: `version = "X.Y.Z"`)
3. Update `README.md` (Latest Release section)
4. Update `CHANGELOG.md` (convert [Unreleased] to [X.Y.Z] with date)
5. Run `uv lock` to update dependency lock file
6. Commit all files together

## Release Commands

```bash
# Check release status
gh release list --limit 5
git log <last-tag>..HEAD --oneline

# Use the agent for releases
# The agent handles: version bump, CHANGELOG, PR, merge, tag, release

# Admin merge (branch protection bypass)
gh pr merge <PR-NUMBER> --admin --squash --delete-branch
```

## Branch Protection Setup

Branch protection configured to allow admin bypass:
- `enforce_admins: false` - Admin can use `--admin` flag
- Required reviews: 1 (for non-admins)
- CodeQL scanning enabled

## Hotfix Workflow (Critical Bugs)

- **Speed target**: 8-10 minutes from bug report to release
- **Process**: Fix → Test → Five-file bump → Commit → github-release-manager agent
- **Branch**: Can go directly to release branch if urgent
- **Issue management**: Post detailed root cause analysis

## Why Agent-First?

**Manual releases** (❌):
- Forgot README.md update
- Incomplete GitHub Release
- Missed workflow verification
- Version mismatch between files
- **Real incident (v10.8.0, Feb 8, 2026)**: Forgot to update `_version.py`, dashboard showed wrong version

**With agent** (✅):
- All files updated consistently (pyproject.toml, _version.py, README.md, CHANGELOG.md)
- Proper release created
- Complete documentation
- CHANGELOG properly formatted
- Dashboard version correct

**Lesson**: Always use github-release-manager agent, even for "simple" hotfixes. The five-file version bump is error-prone when done manually.
