# Release Process

This document outlines the complete release process for pmat, ensuring quality and consistency across all release channels.

## Release Channels

1. **GitHub Releases** - Pre-built binaries and source code
2. **Crates.io** - Rust package registry
3. **Docker Hub** - Container images (planned)

## Release Types

- **Major Release** (X.0.0) - Breaking changes, major features
- **Minor Release** (0.X.0) - New features, backward compatible
- **Patch Release** (0.0.X) - Bug fixes, documentation updates

## Release Workflow

### Step 1: Pre-Release Preparation

```bash
# 1. Ensure on master branch with latest changes
git checkout master
git pull origin master

# 2. Run comprehensive quality checks
make lint
make test-all
make coverage
pmat quality-gate --strict

# 3. Check for SATD
pmat analyze satd

# 4. Verify complexity limits
pmat analyze complexity --max-complexity 20
```

### Step 2: Version Update

```bash
# Update version in server/Cargo.toml
cd server
cargo set-version 0.27.0  # Use appropriate version

# Update lock file
cargo update -p pmat

# Commit version change
git add Cargo.toml Cargo.lock
git commit -m "chore: Bump version to v0.27.0"
```

### Step 3: Update Documentation

1. **RELEASE_NOTES.md**
   ```markdown
   ## v0.27.0 - 2025-07-03

   ### Features
   - Feature description

   ### Bug Fixes
   - Fix description

   ### Documentation
   - Documentation updates

   ### Internal
   - Internal improvements
   ```

2. **README.md**
   - Update version badges if needed
   - Update installation instructions
   - Add new features to feature list

3. **CHANGELOG.md** (if maintained)
   - Add detailed change log

### Step 4: Create Release Commit

```bash
# Stage all changes
git add RELEASE_NOTES.md README.md docs/

# Create release commit
git commit -m "release: Prepare v0.27.0

- Update release notes
- Update documentation
- Bump version in Cargo.toml

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>"

# Push to master
git push origin master
```

### Step 5: Create Git Tag

```bash
# Create annotated tag
git tag -a v0.27.0 -m "Release v0.27.0

See RELEASE_NOTES.md for details"

# Push tag
git push origin v0.27.0
```

### Step 6: Build Release Artifacts

```bash
# Build for multiple platforms
make release-build

# This creates binaries in:
# - target/release/pmat (local platform)
# - target/x86_64-unknown-linux-gnu/release/pmat
# - target/aarch64-unknown-linux-gnu/release/pmat
# - target/x86_64-apple-darwin/release/pmat
# - target/aarch64-apple-darwin/release/pmat
# - target/x86_64-pc-windows-gnu/release/pmat
```

### Step 7: Publish to Crates.io

```bash
cd server

# Dry run first
cargo publish --dry-run

# Publish (use --no-verify if build.rs modifies files)
cargo publish --no-verify

# Verify publication
<!-- PMAT not yet published to crates.io: open https://crates.io/crates/pmat -->
```

### Step 8: Create GitHub Release

1. Go to [GitHub Releases](https://github.com/paiml/paiml-mcp-agent-toolkit/releases)
2. Click "Draft a new release"
3. Select the tag `v0.27.0`
4. Title: `v0.27.0`
5. Copy content from RELEASE_NOTES.md
6. Upload pre-built binaries:
   - `pmat-linux-x86_64.tar.gz`
   - `pmat-linux-aarch64.tar.gz`
   - `pmat-macos-x86_64.tar.gz`
   - `pmat-macos-aarch64.tar.gz`
   - `pmat-windows-x86_64.zip`
7. Check "Set as the latest release"
8. Publish release

### Step 9: Post-Release Verification

```bash
# 1. Test crates.io installation
cargo install pmat --force
pmat --version

# 2. Test binary downloads
curl -L https://github.com/paiml/paiml-mcp-agent-toolkit/releases/download/v0.27.0/pmat-linux-x86_64.tar.gz | tar xz
./pmat --version

# 3. Verify documentation
open https://docs.rs/pmat

# 4. Run smoke tests
pmat context
pmat analyze complexity
pmat quality-gate
```

### Step 10: Announcements

1. **Update README badges** - Ensure version badges show new version
2. **Community announcements** - Post in relevant forums/channels
3. **Update dependent projects** - Notify projects using pmat

## Automated Release Process

### GitHub Actions Workflow

The project includes `.github/workflows/release.yml` for automation:

```yaml
name: Release

on:
  push:
    tags:
      - 'v*'

jobs:
  publish-crates-io:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Rust
        uses: dtolnay/rust-toolchain@stable
      - name: Publish to crates.io
        env:
          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
        run: |
          cd server
          cargo publish --no-verify

  build-binaries:
    strategy:
      matrix:
        include:
          - os: ubuntu-latest
            target: x86_64-unknown-linux-gnu
          - os: ubuntu-latest
            target: aarch64-unknown-linux-gnu
          - os: macos-latest
            target: x86_64-apple-darwin
          - os: macos-latest
            target: aarch64-apple-darwin
          - os: windows-latest
            target: x86_64-pc-windows-msvc
    # ... build and upload steps
```

## Release Checklist

### Pre-Release
- [ ] All tests pass (`make test-all`)
- [ ] Lints pass (`make lint`)
- [ ] Quality gate passes (`pmat quality-gate --strict`)
- [ ] No SATD present (`pmat analyze satd`)
- [ ] Complexity within limits
- [ ] Documentation updated
- [ ] Version bumped in Cargo.toml
- [ ] RELEASE_NOTES.md updated

### Release
- [ ] Git tag created and pushed
- [ ] Published to crates.io
- [ ] GitHub release created
- [ ] Binaries uploaded to release
- [ ] Docs.rs build successful

### Post-Release
- [ ] Installation from crates.io works
- [ ] Binary downloads work
- [ ] Documentation accessible
- [ ] Smoke tests pass
- [ ] Announcements made

## Emergency Procedures

### Yanking a Release

If a critical issue is found after release:

```bash
# Yank from crates.io
cargo yank --version 0.27.0

# Create patch release immediately
# Follow normal release process for 0.27.1
```

### Hotfix Process

1. Create hotfix branch from tag
   ```bash
   git checkout -b hotfix/v0.27.1 v0.27.0
   ```

2. Apply fix and test thoroughly

3. Fast-track through release process

4. Cherry-pick to master if applicable

## Version Naming Convention

- **Stable**: `0.27.0`
- **Pre-release**: `0.27.0-alpha.1`, `0.27.0-beta.1`, `0.27.0-rc.1`
- **Nightly**: `0.27.0-nightly.20250702`

## Release Cadence

- **Major**: As needed for breaking changes
- **Minor**: Monthly for new features
- **Patch**: As needed for bug fixes
- **Security**: Immediate release for security fixes

## Quality Gates

Every release must pass:

1. **Zero SATD** - No technical debt comments
2. **Complexity Limits** - All functions < 20 cyclomatic complexity
3. **Test Coverage** - Minimum 90% coverage
4. **Clean Lints** - All clippy pedantic/nursery warnings resolved
5. **Documentation** - All public APIs documented

## Release Notes Template

```markdown
## vX.Y.Z - YYYY-MM-DD

### 🎉 Features
- Brief description of new feature (#PR)

### 🐛 Bug Fixes
- Brief description of fix (#PR)

### 📚 Documentation
- Documentation improvements (#PR)

### 🔧 Internal
- Internal improvements (#PR)

### 🙏 Contributors
- @username - contribution description

**Full Changelog**: https://github.com/paiml/paiml-mcp-agent-toolkit/compare/vX.Y.Y...vX.Y.Z
```

## Rollback Procedure

If issues are discovered post-release:

1. **Assess Impact** - Determine severity and scope
2. **Communicate** - Notify users of known issues
3. **Yank if Critical** - Remove from crates.io if severe
4. **Prepare Fix** - Fast-track patch release
5. **Post-Mortem** - Document lessons learned

Remember: Quality over speed. Never rush a release!