Releasing Versions

When to Use

• Preparing a new release
• Version bumping
• Pre-release validation
• Documentation verification before release

Release Workflow Overview

Phase	Purpose	Blocking?
1. Pre-Release Validation	Tests, security	Yes
2. Version Bump	Update version strings	Yes
3. Documentation	Verify/update docs	Warning
4. Template Sync	Cookiecutter alignment	Warning
5. Build Verification	Package builds	Yes
6. Git Operations	Commit and tag	Yes

Phase 1: Pre-Release Validation

1.1 Verify Sprint Tasks Complete

# Check for incomplete tasks
bpsai-pair task list --status in_progress
bpsai-pair task list --status blocked

# Check current state
bpsai-pair status

BLOCKER: All tasks must be complete or moved to next sprint.

1.2 Run Full Test Suite

# All tests must pass
pytest tests/ -v --tb=short

# Check coverage meets target (80%)
pytest tests/ --cov=bpsai_pair --cov-report=term-missing --cov-fail-under=80

BLOCKER: Release cannot proceed if tests fail.

1.3 Security Scans

# Scan for accidentally committed secrets
bpsai-pair security scan-secrets

# Scan dependencies for known vulnerabilities
bpsai-pair security scan-deps

BLOCKER: Secrets detected = cannot release. WARNING: Dependency vulnerabilities should be reviewed but may not block.

Phase 2: Version Bump

Locate Version Files

grep -E "^version|__version__" tools/cli/pyproject.toml tools/cli/bpsai_pair/__init__.py

Update Both Files

File	Format
pyproject.toml	version = "X.Y.Z"
__init__.py	__version__ = "X.Y.Z"

Note: Version in files has NO 'v' prefix. Git tags use 'v' prefix.

Related Files to Update

File	Update
capabilities.yaml	version: "X.Y.Z"
config.yaml	version: "X.Y.Z"

Phase 3: Documentation Verification

3.1 Required Documentation

# Check CHANGELOG has entry for this version
grep -A 20 "## \[X.Y.Z\]" CHANGELOG.md

# Check README mentions current features
head -100 README.md

# Check FEATURE_MATRIX is current
head -50 .paircoder/docs/FEATURE_MATRIX.md

3.2 Documentation Freshness

# Check modification dates
git log -1 --format="%ci" -- README.md
git log -1 --format="%ci" -- CHANGELOG.md
git log -1 --format="%ci" -- .paircoder/docs/FEATURE_MATRIX.md

WARNING if any required doc older than 7 days - may need update.

3.3 CHANGELOG Entry Format

If missing, create entry following Keep a Changelog format:

## [X.Y.Z] - YYYY-MM-DD

### Added
- Feature 1
- Feature 2

### Changed
- Change 1

### Fixed
- Fix 1

### Removed
- (if applicable)

Generate content from archived tasks:

bpsai-pair task changelog-preview --since <last-version>

Phase 4: Template Sync (PairCoder Only)

Verify cookiecutter template matches current version:

# Check template exists
ls -la tools/cli/bpsai_pair/data/cookiecutter-paircoder/

# Compare key files
diff .paircoder/config.yaml \
  tools/cli/bpsai_pair/data/cookiecutter-paircoder/{{cookiecutter.project_slug}}/.paircoder/config.yaml

diff CLAUDE.md \
  tools/cli/bpsai_pair/data/cookiecutter-paircoder/{{cookiecutter.project_slug}}/CLAUDE.md

Key files that should stay in sync:

• config.yaml structure (not values)
• CLAUDE.md instructions
• capabilities.yaml format
• Skill files

Phase 5: Build Verification

# Clean old builds
rm -rf tools/cli/dist/ tools/cli/build/ tools/cli/*.egg-info

# Build the package
cd tools/cli && pip install build && python -m build

# Verify clean install
pip install dist/*.whl --force-reinstall

# Verify version is correct
bpsai-pair --version

Phase 6: Release Checklist

• [ ] All sprint tasks complete
• [ ] Tests passing (100%)
• [ ] Coverage ≥ 80%
• [ ] No secrets in codebase
• [ ] Version bumped in pyproject.toml
• [ ] Version bumped in init.py
• [ ] Version bumped in capabilities.yaml
• [ ] Version bumped in config.yaml
• [ ] CHANGELOG updated
• [ ] README current
• [ ] FEATURE_MATRIX updated
• [ ] Cookiecutter template synced (if applicable)
• [ ] Package builds successfully
• [ ] Package installs cleanly

Phase 7: Git Operations

# Stage all changes
git add -A

# Commit with release message
git commit -m "Release vX.Y.Z"

# Create annotated tag
git tag -a "vX.Y.Z" -m "Release vX.Y.Z"

# Show what will be pushed
git log --oneline -5
git tag -l | tail -5

DO NOT push yet - let user review and confirm.

Phase 8: Report Summary

📦 **Release Prepared**: vX.Y.Z

**Pre-Release Checks**:
- ✅ All tasks complete
- ✅ Tests: XXX passed
- ✅ Coverage: XX%
- ✅ Security: Clean

**Documentation**:
- ✅ CHANGELOG: Updated
- ✅ README: Current
- ✅ FEATURE_MATRIX: Updated
- ⚠️ User guide: Last updated X days ago (review recommended)

**Cookiecutter**: 
- ✅ Template synced

**Build**:
- ✅ Package built: bpsai_pair-X.Y.Z-py3-none-any.whl
- ✅ Installs cleanly
- ✅ Version verified

**Ready to Release**:
```bash
git push origin main
git push origin vX.Y.Z

Then publish to PyPI:

cd tools/cli && twine upload dist/*

## Error Recovery

### Tests Fail
1. Do not proceed with release
2. Fix failing tests
3. Re-run from Phase 1

### Secrets Detected
1. Do not proceed with release
2. Remove secrets from history (git filter-branch or BFG)
3. Rotate any exposed credentials
4. Re-run security scan

### Documentation Stale
1. WARNING, not blocker
2. User can choose to update or proceed
3. Log the decision

### Cookiecutter Differs
1. Determine if difference is intentional
2. If template should be updated, do so
3. If difference is project-specific, document why

## Configuration Reference

Release configuration in `config.yaml`:

```yaml
release:
  version_source: tools/cli/pyproject.toml
  documentation:
    - CHANGELOG.md
    - README.md
    - .paircoder/docs/FEATURE_MATRIX.md
  cookie_cutter:
    template_path: tools/cli/bpsai_pair/data/cookiecutter-paircoder
    sync_required: true
  freshness_days: 7

Version Format Reference

Location	Format	Example
pyproject.toml	X.Y.Z	2.9.0
init.py	X.Y.Z	2.9.0
Git tags	vX.Y.Z	v2.9.0
CHANGELOG	[X.Y.Z]	[2.9.0]