OpenZIM MCP Server

# Release System Guide Comprehensive guide to OpenZIM MCP's automated release system with enterprise-grade CI/CD pipeline. ## Overview OpenZIM MCP features a sophisticated automated release system built on [Release Please](https://github.com/googleapis/release-please) and GitHub Actions. This enterprise-grade system ensures reliable, consistent releases with comprehensive validation and automated deployment. ## Release System Architecture ### Components ``` ┌─────────────────────────────────────────────────────────────┐ │ Release System Architecture │ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │ │ │ Conventional│ │ Release │ │ GitHub Actions │ │ │ │ Commits │ │ Please │ │ Workflows │ │ │ │ │ │ │ │ │ │ │ │ • feat: │ │ • Version │ │ • CI/CD Pipeline │ │ │ │ • fix: │ │ • Changelog │ │ • Testing │ │ │ │ • docs: │ │ • Tags │ │ • PyPI Deployment │ │ │ └─────────────┘ └─────────────┘ └─────────────────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` ### Release Flow ``` 1. Developer Commits (Conventional Format) ↓ 2. Release Please Analysis ↓ 3. Version Calculation (SemVer) ↓ 4. Release PR Creation ↓ 5. Code Review & Approval ↓ 6. PR Merge → Release Trigger ↓ 7. Automated Testing ↓ 8. Build & Package ↓ 9. PyPI Deployment ↓ 10. GitHub Release Creation ``` ## Conventional Commits ### Commit Format ``` <type>[optional scope]: <description> [optional body] [optional footer(s)] ``` ### Commit Types | Type | Description | Version Impact | Example | |------|-------------|----------------|---------| | `feat` | New feature | Minor (0.x.0) | `feat: add search suggestions endpoint` | | `fix` | Bug fix | Patch (0.0.x) | `fix: resolve path traversal vulnerability` | | `feat!` | Breaking change | Major (x.0.0) | `feat!: change API response format` | | `docs` | Documentation | None | `docs: update installation instructions` | | `style` | Code style | None | `style: format code with black` | | `refactor` | Code refactoring | None | `refactor: improve cache implementation` | | `test` | Add/update tests | None | `test: add integration tests` | | `chore` | Maintenance | None | `chore: update dependencies` | | `perf` | Performance | Patch (0.0.x) | `perf: optimize search algorithm` | ### Breaking Changes Indicate breaking changes with `!` or `BREAKING CHANGE:` footer: ```bash # Method 1: Exclamation mark feat!: change search API response format # Method 2: Footer feat: update search functionality BREAKING CHANGE: Search results now return different JSON structure ``` ### Examples **Feature Addition**: ```bash feat: add multi-instance conflict detection Implements automatic detection of server instance conflicts with configurable sensitivity levels and resolution strategies. Closes #123 ``` **Bug Fix**: ```bash fix: resolve cache invalidation issue Cache entries were not being properly invalidated when TTL expired, causing stale data to be returned. This fix ensures proper cleanup. Fixes #456 ``` **Documentation Update**: ```bash docs: add smart retrieval system guide Comprehensive documentation for the intelligent entry retrieval system including configuration options and troubleshooting. ``` ## Release Process ### Automatic Releases (Recommended) 1. **Write Conventional Commits**: ```bash git commit -m "feat: add new search feature" git push origin main ``` 2. **Release Please Creates PR**: - Analyzes commit history - Calculates next version - Updates CHANGELOG.md - Creates release PR 3. **Review and Merge**: - Review the release PR - Approve and merge - Automatic release triggered 4. **Automated Deployment**: - Tests run automatically - Package built and uploaded to PyPI - GitHub release created ### Manual Releases For emergency releases or special cases: 1. **Trigger Manual Release**: - Go to GitHub Actions - Select "Release" workflow - Click "Run workflow" - Specify tag (optional) 2. **Direct Tag Creation**: ```bash git tag v0.5.0 git push origin v0.5.0 ``` ### Release Validation The system includes comprehensive validation: #### Version Synchronization - Validates `pyproject.toml` version - Validates `__init__.py` version - Ensures consistency across files #### Testing Requirements - All tests must pass - Code coverage requirements met - Security scans completed #### Build Validation - Package builds successfully - Dependencies resolved correctly - Distribution files created ## Configuration ### Release Please Configuration **`.release-please-config.json`**: ```json { "release-type": "python", "package-name": "openzim-mcp", "include-component-in-tag": false, "include-v-in-tag": true, "versioning": "default", "bump-minor-pre-major": true, "bump-patch-for-minor-pre-major": true, "draft": false, "prerelease": false, "changelog-sections": [ {"type": "feat", "section": "Features"}, {"type": "fix", "section": "Bug Fixes"}, {"type": "perf", "section": "Performance Improvements"}, {"type": "docs", "section": "Documentation"}, {"type": "deps", "section": "Dependencies"} ] } ``` ### GitHub Actions Workflows #### Release Please Workflow ```yaml name: Release Please on: push: branches: [main] workflow_dispatch: jobs: release-please: runs-on: ubuntu-latest steps: - uses: google-github-actions/release-please-action@v4 with: release-type: python package-name: openzim-mcp ``` #### Release Workflow ```yaml name: Release on: release: types: [published] workflow_dispatch: inputs: tag: description: 'Tag to release' required: false jobs: test: runs-on: ubuntu-latest steps: - name: Run comprehensive tests - name: Validate version synchronization - name: Security scanning build: needs: test runs-on: ubuntu-latest steps: - name: Build package - name: Upload to PyPI - name: Create GitHub release ``` ## Release Metrics ### Version History Track release frequency and types: ``` v0.4.0 (2025-09-15) - Major feature release ├── feat: overhaul release system ├── feat: add multi-instance management └── feat: enhance smart retrieval v0.3.1 (2025-09-15) - Bug fix release ├── fix: add manual trigger support └── fix: ensure correct tag checkout v0.3.0 (2025-09-15) - Feature release └── feat: add automated version bumping ``` ### Release Statistics - **Average time between releases**: 2-3 days - **Release success rate**: 98% - **Automated vs manual releases**: 95% automated - **Breaking changes frequency**: <5% of releases ## Troubleshooting ### Common Issues #### Issue: Release Please Not Creating PR **Symptoms**: No release PR after conventional commits **Causes**: - Non-conventional commit messages - No releasable changes - Workflow permissions **Solutions**: 1. Check commit message format 2. Verify workflow permissions 3. Manually trigger workflow #### Issue: Version Synchronization Failure **Symptoms**: Release workflow fails with version mismatch **Causes**: - Manual version edits - Merge conflicts - Incomplete updates **Solutions**: 1. Check `pyproject.toml` and `__init__.py` 2. Ensure versions match 3. Re-run release process #### Issue: PyPI Deployment Failure **Symptoms**: Package build succeeds but PyPI upload fails **Causes**: - Authentication issues - Version already exists - Package validation errors **Solutions**: 1. Check PyPI credentials 2. Verify version uniqueness 3. Validate package structure ### Diagnostic Commands #### Check Release Status ```bash # View recent releases gh release list # Check workflow status gh run list --workflow=release.yml ``` #### Validate Version Sync ```bash # Check pyproject.toml version grep version pyproject.toml # Check __init__.py version grep __version__ openzim_mcp/__init__.py ``` #### Test Release Process ```bash # Dry run release python -m build twine check dist/* ``` ## Future Enhancements ### Planned Improvements 1. **Pre-release Support**: - Alpha/beta release channels - Feature flag management - Staged rollouts 2. **Enhanced Validation**: - Integration test requirements - Performance benchmarks - Security compliance checks 3. **Release Analytics**: - Usage metrics integration - Error rate monitoring - Rollback capabilities 4. **Multi-environment Deployment**: - Staging environment validation - Canary deployments - Blue-green releases ### Integration Opportunities - **Container Registry**: Docker image releases - **Package Managers**: Conda, Homebrew support - **Documentation**: Automatic docs deployment - **Monitoring**: Release impact tracking --- **Need help with releases?** Check the [Release Process Guide](https://github.com/cameronrye/openzim-mcp/blob/main/docs/RELEASE_PROCESS_GUIDE.md) for detailed instructions.