MCP WordPress Server

# Release Process Guide Complete guide to the automated release pipeline, semantic versioning, and deployment process for the MCP WordPress Server. ## 🚀 Release Pipeline Overview The project uses a fully automated release system based on conventional commits and semantic versioning. ### Release Workflow ```text Feature Development → Pull Request → Main Branch → Automated Release ↓ ↓ ↓ Code Review CI/CD Tests Publishing ``` ## 📋 Semantic Versioning We follow [Semantic Versioning](https://semver.org/) strictly: ### Version Format: `MAJOR.MINOR.PATCH` - **MAJOR** (`1.0.0 → 2.0.0`): Breaking changes - **MINOR** (`1.0.0 → 1.1.0`): New features (backward compatible) - **PATCH** (`1.0.0 → 1.0.1`): Bug fixes (backward compatible) ### Pre-release Versions - **Alpha** (`1.0.0-alpha.1`): Early development - **Beta** (`1.0.0-beta.1`): Feature complete, testing - **Release Candidate** (`1.0.0-rc.1`): Production ready, final testing ## 🔄 Conventional Commits Our automated release system reads commit messages to determine version bumps. ### Commit Message Format ```text <type>[optional scope]: <description> [optional body] [optional footer(s)] ``` ### Commit Types ```bash # PATCH version bump fix: resolve authentication header issue in POST requests fix(auth): handle JWT token expiration gracefully fix(cache): fix cache invalidation for multi-site setups # MINOR version bump feat: add new WordPress plugin management tool feat(tools): add bulk comment moderation functionality feat(api): add support for custom post types # MAJOR version bump (breaking change) feat!: redesign authentication system API fix!: change client configuration interface feat(api)!: remove deprecated methods # No version bump docs: update API documentation for media tools style: fix code formatting with Prettier test: add performance tests for cache system chore: update dependencies to latest versions ci: improve GitHub Actions workflow refactor: improve error handling in request manager ``` ### Breaking Changes ```bash # Using exclamation mark feat!: change authentication configuration format # Using footer feat: add new authentication method BREAKING CHANGE: The authentication configuration format has changed. See MIGRATION.md for upgrade instructions. ``` ## 🏭 Automated Release System ### Release Triggers **Automatic Release**: - Push to `main` branch with conventional commits - Creates version bump based on commit types - Publishes to NPM and Docker Hub automatically **Manual Release**: - Workflow dispatch with manual version override - Emergency releases and hotfixes - Pre-release versions ### Release Workflow (`.github/workflows/release.yml`) ```yaml name: 🚀 Release & Publish on: push: branches: [main] workflow_dispatch: inputs: release_type: description: "Release type" required: true default: "patch" type: choice options: ["patch", "minor", "major", "prerelease"] jobs: release: name: 🚀 Semantic Release runs-on: ubuntu-latest steps: - name: 📥 Checkout Code uses: actions/checkout@v4 with: fetch-depth: 0 token: ${{ secrets.GITHUB_TOKEN }} - name: 📦 Setup Node.js uses: actions/setup-node@v4 with: node-version: "20" cache: "npm" - name: 📦 Install Dependencies run: npm ci - name: 🧪 Run Tests run: npm test - name: 🔒 Security Audit run: npm audit --audit-level=high - name: 🏗️ Build Project run: npm run build - name: 🚀 Semantic Release env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} NPM_TOKEN: ${{ secrets.NPM_TOKEN }} DOCKER_USERNAME: ${{ secrets.DOCKER_USERNAME }} DOCKER_PASSWORD: ${{ secrets.DOCKER_PASSWORD }} run: npx semantic-release ``` ## 📦 Publishing Targets ### NPM Package **Registry**: [npmjs.com/package/mcp-wordpress](https://www.npmjs.com/package/mcp-wordpress) **Publishing Process**: 1. Semantic release determines version 2. Package built and tested 3. Published to NPM registry 4. Provenance generated for security **Package Configuration**: ```json { "name": "mcp-wordpress", "version": "0.0.0-development", "publishConfig": { "access": "public", "provenance": true } } ``` ### Docker Images **Registry**: [hub.docker.com/r/docdyhr/mcp-wordpress](https://hub.docker.com/r/docdyhr/mcp-wordpress) **Multi-Architecture Support**: - `linux/amd64` (Intel/AMD 64-bit) - `linux/arm64` (ARM 64-bit, Apple Silicon) **Image Tags**: - `latest` - Latest stable release - `1.3.1` - Specific version - `v1.3.1` - Version with v prefix ### GitHub Releases **Automatic Release Notes**: - Generated from conventional commits - Categorized by change type - Breaking changes highlighted - Contributors automatically credited ## 🔧 Release Configuration ### Semantic Release Configuration (`.releaserc.json`) ```json { "branches": ["main"], "plugins": [ "@semantic-release/commit-analyzer", "@semantic-release/release-notes-generator", "@semantic-release/changelog", "@semantic-release/npm", [ "@semantic-release/exec", { "publishCmd": "docker buildx build --platform linux/amd64,linux/arm64 --tag docdyhr/mcp-wordpress:${nextRelease.version} --tag docdyhr/mcp-wordpress:latest --push ." } ], [ "@semantic-release/github", { "assets": [ { "path": "dist/**", "label": "Distribution files" } ] } ] ] } ``` ### Commit Analysis Configuration ```json { "preset": "conventionalcommits", "releaseRules": [ { "type": "feat", "release": "minor" }, { "type": "fix", "release": "patch" }, { "type": "perf", "release": "patch" }, { "type": "docs", "release": false }, { "type": "style", "release": false }, { "type": "refactor", "release": "patch" }, { "type": "test", "release": false }, { "type": "build", "release": "patch" }, { "type": "ci", "release": false }, { "type": "chore", "release": false }, { "breaking": true, "release": "major" } ] } ``` ## 🔍 Release Verification ### Automated Verification (`verify-release.yml`) **Post-Release Verification**: 1. **NPM Verification**: Check package availability 2. **Docker Verification**: Verify image publishing 3. **GitHub Release**: Confirm release creation 4. **Integration Test**: Basic functionality test **Verification Process**: ```yaml - name: 📦 Verify NPM Publishing run: | VERSION=$(node -p "require('./package.json').version") if npm view mcp-wordpress@$VERSION version; then echo "✅ NPM package published successfully" else echo "❌ NPM package not found" exit 1 fi - name: 🐳 Verify Docker Publishing run: | VERSION=$(node -p "require('./package.json').version") if curl -s https://hub.docker.com/v2/repositories/docdyhr/mcp-wordpress/tags | jq -e ".results[] | select(.name == \"$VERSION\")"; then echo "✅ Docker image published successfully" else echo "❌ Docker image not found" exit 1 fi ``` ### Manual Verification ```bash # Check NPM package npm view mcp-wordpress@latest # Test NPM installation npm install -g mcp-wordpress@latest mcp-wordpress --version # Test Docker image docker pull docdyhr/mcp-wordpress:latest docker run --rm docdyhr/mcp-wordpress:latest --version # Verify GitHub release gh release view --repo docdyhr/mcp-wordpress ``` ## 🐛 Hotfix Process ### Emergency Releases For critical bugs requiring immediate fixes: 1. **Create Hotfix Branch**: ```bash git checkout main git pull origin main git checkout -b hotfix/critical-auth-fix ``` 2. **Implement Fix**: ```bash # Make minimal changes git add . git commit -m "fix: resolve critical authentication vulnerability" ``` 3. **Create Pull Request**: - Target: `main` branch - Label: `hotfix`, `critical` - Skip normal review process if approved 4. **Fast-Track Release**: ```bash # Merge and release immediately git checkout main git merge hotfix/critical-auth-fix git push origin main ``` ### Hotfix Guidelines - **Minimal Changes**: Only fix the critical issue - **No Feature Additions**: Hotfixes should not include new features - **Comprehensive Testing**: Even expedited, must pass all tests - **Documentation**: Update if user-facing changes ## 📊 Release Metrics ### Release Health Dashboard **Key Metrics**: - **Release Frequency**: ~2-3 releases per month - **Lead Time**: Feature to production < 1 week - **Success Rate**: 95%+ successful releases - **Rollback Rate**: < 5% require rollbacks ### Monitoring ```bash # Release frequency gh release list --limit 10 # Download statistics npm view mcp-wordpress --json | jq '.downloads' # Docker pulls curl -s https://hub.docker.com/v2/repositories/docdyhr/mcp-wordpress/ | jq '.pull_count' ``` ## 🔄 Rollback Process ### Automatic Rollback Triggers - **Critical Test Failures**: Automated rollback on CI failure - **Publishing Failures**: Rollback if NPM/Docker publishing fails - **Integration Failures**: Rollback on post-release verification failure ### Manual Rollback Process ```bash # Identify last known good version gh release list # Revert to previous version git checkout main git revert <commit-hash> git commit -m "revert: rollback to v1.2.3 due to critical issue" git push origin main # Emergency NPM rollback npm deprecate mcp-wordpress@1.2.4 "Critical issue, use 1.2.3" npm dist-tag add mcp-wordpress@1.2.3 latest ``` ## 📚 Release Documentation ### Changelog Generation **Automatic Changelog**: - Generated from conventional commits - Categorized by change type - Links to issues and PRs - Breaking changes highlighted **Changelog Format**: ```markdown # [1.3.0](https://github.com/docdyhr/mcp-wordpress/compare/v1.2.0...v1.3.0) (2024-01-15) ### Features - add new WordPress plugin management tool ([abc123](https://github.com/docdyhr/mcp-wordpress/commit/abc123)) - improve authentication system ([def456](https://github.com/docdyhr/mcp-wordpress/commit/def456)) ### Bug Fixes - resolve cache invalidation issue ([ghi789](https://github.com/docdyhr/mcp-wordpress/commit/ghi789)) ### BREAKING CHANGES - authentication configuration format has changed ``` ### Migration Guides For breaking changes, create migration guides in `docs/developer/MIGRATION_GUIDE.md`: ````markdown ## Migrating from v1.x to v2.x ### Authentication Configuration Changes **Before (v1.x)**: ```javascript { auth: { username: 'admin', password: 'password' } } ``` ```` **After (v2.x)**: ```javascript { authentication: { method: 'app-password', username: 'admin', appPassword: 'xxxx xxxx xxxx xxxx xxxx xxxx' } } ``` ## 🔒 Security Considerations ### Release Security **Supply Chain Security**: - NPM provenance enabled - Signed commits required - Dependency scanning - SLSA compliance **Secret Management**: - Publishing tokens in GitHub Secrets - No secrets in source code - Automated secret rotation **Vulnerability Response**: - Security patches prioritized - CVE disclosure process - Automated dependency updates ## 📈 Release Planning ### Release Schedule **Regular Releases**: - **Minor Releases**: Monthly (new features) - **Patch Releases**: Bi-weekly (bug fixes) - **Major Releases**: Quarterly (breaking changes) **Special Releases**: - **Security Releases**: As needed (immediate) - **Hotfixes**: As needed (critical bugs) - **Pre-releases**: Before major versions ### Feature Planning **Release Branches Strategy**: - `main`: Latest stable release - `develop`: Next minor version development - `feature/*`: Individual feature development - `hotfix/*`: Critical bug fixes ## 📚 Further Reading - **[Build System](BUILD_SYSTEM.md)** - TypeScript compilation and build process - **[CI/CD Pipeline](CI_CD_PIPELINE.md)** - GitHub Actions workflows - **[Migration Guide](MIGRATION_GUIDE.md)** - Breaking changes and migration paths - **[Contributing Guidelines](CONTRIBUTING.md)** - How to contribute --- **Planning a release?** This automated system ensures consistent, reliable releases while maintaining high quality standards. Every release is tested, verified, and documented automatically.