# Pre-Publish Checklist

Quick actionable checklist for publishing Claude MPM to PyPI.

## Quick Start (1 minute)

```bash
# Complete publishing workflow
make pre-publish           # Cleanup + quality checks
make safe-release-build    # Build with quality gates
make publish-pypi          # Publish to PyPI
```

## Pre-Publish Steps

### Step 1: Automated Cleanup

Run automated cleanup to remove temporary files before publishing:

- [ ] Run `make pre-publish` (includes cleanup automatically)
- [ ] Verify cleanup completed successfully
- [ ] Check no production code was affected

**What gets cleaned**:
- `.DS_Store` files (macOS Finder metadata)
- `__pycache__` directories (Python bytecode cache)
- `.pyc` / `.pyo` files (compiled Python files)
- Root test artifacts (`dashboard_test.html`, `report_qa_test.html`, `coverage.json`)
- Deprecated documentation files

**Manual cleanup commands** (if needed):
```bash
make clean-pre-publish      # Safe automated cleanup
make clean-system-files     # Remove .DS_Store, __pycache__, *.pyc
make clean-test-artifacts   # Remove test HTML/JSON files
make clean-deprecated       # Remove deprecated docs
```

### Step 2: Quality Gates

All quality gates must pass before publishing:

- [ ] All tests passing (230+ tests)
  ```bash
  make test
  ```

- [ ] Linting clean (no errors)
  ```bash
  make lint
  ```

- [ ] Security scan clear
  ```bash
  make security-scan
  ```

- [ ] Type checking passed
  ```bash
  make type-check
  ```

**Automated check**:
```bash
make pre-publish  # Runs all quality gates
```

### Step 3: Version & Release Preparation

- [ ] Version bumped correctly
  ```bash
  ./scripts/manage_version.py bump patch
  # Or: make auto-patch
  # Or: make increment-build
  ```

- [ ] CHANGELOG.md updated with release notes

- [ ] Git working directory is clean
  ```bash
  git status  # Should show no uncommitted changes
  ```

- [ ] Changes committed
  ```bash
  git add VERSION CHANGELOG.md
  git commit -m "chore: bump version to X.Y.Z"
  ```

### Step 4: Build Distribution

- [ ] Build successful
  ```bash
  make safe-release-build
  ```

- [ ] Distribution files created
  ```bash
  ls -lh dist/
  # Should show:
  # - claude_mpm-X.Y.Z-py3-none-any.whl
  # - claude_mpm-X.Y.Z.tar.gz
  ```

- [ ] File sizes are reasonable (wheel ~3MB, tarball ~2.5MB)

### Step 5: Publishing Setup Verification

- [ ] `.env.local` file exists with API key
  ```bash
  ls -la .env.local
  ```

- [ ] File permissions are secure (600)
  ```bash
  chmod 600 .env.local
  ```

- [ ] API key is valid and not expired

- [ ] Setup verification passes
  ```bash
  ./scripts/verify_publish_setup.sh
  ```

### Step 6: Publish to PyPI

- [ ] Publish command executed
  ```bash
  make publish-pypi
  # Or: ./scripts/publish_to_pypi.sh
  ```

- [ ] Upload completed successfully

- [ ] PyPI confirmation received

### Step 7: Verify Publication

- [ ] PyPI package page updated
  - Visit: https://pypi.org/project/claude-mpm/
  - Check correct version is displayed
  - Verify description renders properly
  - Confirm files are present

- [ ] Installation verified in clean environment
  ```bash
  python -m venv test_env
  source test_env/bin/activate
  pip install --upgrade claude-mpm
  claude-mpm --version
  deactivate
  rm -rf test_env
  ```

- [ ] Upgrade works for existing installations
  ```bash
  pip install --upgrade claude-mpm
  ```

### Step 8: Create GitHub Release

- [ ] Git tag created
  ```bash
  git tag vX.Y.Z
  ```

- [ ] Tag pushed to remote
  ```bash
  git push origin vX.Y.Z
  ```

- [ ] GitHub release created
  ```bash
  gh release create vX.Y.Z \
      --title "Release X.Y.Z" \
      --notes "Release notes here"
  ```

- [ ] Changes pushed to main
  ```bash
  git push origin main
  ```

## Cleanup Details

### Automatic Cleanup Process

The `make pre-publish` target automatically runs cleanup before quality checks:

1. **System Files** (across entire project):
   - `.DS_Store` - macOS Finder metadata
   - `__pycache__/` - Python bytecode cache directories
   - `*.pyc`, `*.pyo` - Compiled Python files
   - Excludes `venv/` and `.venv/` directories

2. **Root Test Artifacts**:
   - `dashboard_test.html` - Temporary dashboard test file
   - `report_qa_test.html` - Temporary QA report test file
   - `coverage.json` - Test coverage report (regenerated by tests)

3. **Deprecated Documentation**:
   - `src/claude_mpm/agents/INSTRUCTIONS_OLD_DEPRECATED.md`

### Manual Review Required (Periodic)

**Debug Scripts** - Review quarterly:
```bash
make clean-debug  # Requires confirmation
```
- `tools/dev/debug_*.py` (30+ files)
- `scripts/development/debug_*.py` (12+ files)

**Archived Test Files** - Review before major releases:
- `tests/test-temp-memory/` - Temporary test memory
- `src/claude_mpm/dashboard/static/archive/` - Old HTML test files (24+)
- `tests/artifacts/reports/` - Old test reports

### Cleanup Statistics

**Files cleaned per release**:
- 186+ files/directories on average
- 115+ `__pycache__` directories
- 10+ `.DS_Store` files
- 2 root HTML test files
- 1 root coverage.json
- 1 deprecated documentation file
- 50+ test artifact JSON files

**Space saved**:
- Estimated 50-100 MB per cleanup
- Prevents accumulation of temporary files
- Keeps git repository clean

### Safety Features

Protection mechanisms in cleanup:
- All `find` commands exclude `venv/` and `.venv/`
- Commands use `2>/dev/null || true` to prevent errors
- `clean-debug` requires manual Y/N confirmation
- Color-coded output for visibility

What won't be deleted:
- Core test suite in `tests/` directory
- Active development tools
- Current documentation
- Historical verification reports
- Any files tracked in version control

## Common Issues

### Issue: Tests Failing

**Solution**:
```bash
# Run tests to see failures
make test

# Fix failing tests
# Re-run until all pass
make test
```

### Issue: Linting Errors

**Solution**:
```bash
# See linting issues
make lint

# Auto-fix many issues
make format

# Fix remaining issues manually
```

### Issue: Version Already Exists on PyPI

**Solution**:
```bash
# Bump version
./scripts/manage_version.py bump build

# Rebuild
make safe-release-build

# Publish new version
make publish-pypi
```

### Issue: Distribution Files Missing

**Solution**:
```bash
# Build distribution files
make safe-release-build

# Verify files exist
ls -lh dist/
```

### Issue: .env.local Not Found

**Solution**:
```bash
# Create .env.local with your API key
echo "PYPI_API_KEY=pypi-YOUR-TOKEN-HERE" > .env.local
chmod 600 .env.local

# Verify setup
./scripts/verify_publish_setup.sh
```

### Issue: Invalid API Token

**Solution**:
1. Go to https://pypi.org/manage/account/token/
2. Revoke old token
3. Create new token for `claude-mpm` project
4. Update `.env.local` with new token
5. Verify: `./scripts/verify_publish_setup.sh`

### Issue: Permission Denied on .env.local

**Solution**:
```bash
# Fix file permissions
chmod 600 .env.local

# Verify
ls -la .env.local
# Should show: -rw-------
```

## Security Checklist

Before publishing, verify:

- [ ] `.env.local` has 600 permissions (`chmod 600 .env.local`)
- [ ] `.env.local` is gitignored (`git check-ignore .env.local`)
- [ ] API token is project-scoped (not account-wide)
- [ ] Never committed `.env.local` (`git status .env.local` shows error)
- [ ] Never shared API token via email/Slack/screenshots
- [ ] Token is stored in password manager as backup
- [ ] Token will be rotated in 90-180 days

## Commands Reference

```bash
# Pre-publish workflow
make pre-publish           # Cleanup + all quality gates
make safe-release-build    # Build with quality checks
make publish-pypi          # Publish to PyPI

# Individual cleanup targets
make clean-pre-publish     # Automated cleanup only
make clean-system-files    # Remove .DS_Store, __pycache__, *.pyc
make clean-test-artifacts  # Remove test HTML/JSON files
make clean-deprecated      # Remove deprecated documentation
make clean-debug           # Remove debug scripts (requires confirmation)

# Verification
./scripts/verify_publish_setup.sh  # Verify publishing setup

# Version management
./scripts/manage_version.py bump patch  # Bump patch version
./scripts/manage_version.py bump minor  # Bump minor version
./scripts/manage_version.py bump major  # Bump major version
make increment-build       # Increment build number only
make auto-patch            # Auto bump patch

# Build and test
make test                  # Run all tests
make lint                  # Run linting
make format                # Auto-format code
make security-scan         # Run security scan
make type-check            # Run type checking

# Publishing
make publish-pypi          # Publish to PyPI
./scripts/publish_to_pypi.sh  # Direct script execution

# Git operations
git tag vX.Y.Z            # Create version tag
git push origin vX.Y.Z    # Push tag
gh release create vX.Y.Z  # Create GitHub release

# Verification
pip install --upgrade claude-mpm  # Test installation
claude-mpm --version      # Verify version
```

## Publishing Workflow Summary

**Complete workflow in order**:

1. **Cleanup & Quality**: `make pre-publish`
2. **Version Bump**: `./scripts/manage_version.py bump patch`
3. **Update Changelog**: Edit `CHANGELOG.md`
4. **Commit Changes**: `git commit -am "chore: bump version"`
5. **Build**: `make safe-release-build`
6. **Verify Build**: `ls -lh dist/`
7. **Publish**: `make publish-pypi`
8. **Verify PyPI**: Visit https://pypi.org/project/claude-mpm/
9. **Test Install**: `pip install --upgrade claude-mpm`
10. **Tag**: `git tag vX.Y.Z && git push origin vX.Y.Z`
11. **GitHub Release**: `gh release create vX.Y.Z`
12. **Push**: `git push origin main`

## Full Documentation

- [Publishing Guide](./publishing-guide.md) - Comprehensive publishing documentation
- [Release Process](../RELEASE_PROCESS.md) - Complete release workflow
- [Version Management](../VERSION_MANAGEMENT.md) - Version numbering scheme
- [Quality Gates](../QUALITY_GATES.md) - Pre-release checks

## Support

- **Quick Help**: Run `make help | grep publish`
- **Verify Setup**: `./scripts/verify_publish_setup.sh`
- **PyPI Package**: https://pypi.org/project/claude-mpm/
- **Issues**: https://github.com/bobmatnyc/claude-mpm/issues
