# Publishing Troubleshooting Guide

## Overview

This guide helps troubleshoot and resolve publishing issues for the MCP WordPress project. The project publishes to two
main targets:

1. **NPM Registry** - Node.js package
2. **Docker Hub** - Container images

## Automated Publishing Process

### Normal Flow

1. **Push to main branch** → triggers semantic-release
2. **Semantic-release** → creates release, publishes to NPM, creates GitHub release
3. **GitHub release created** → triggers Docker publishing
4. **Verification workflow** → checks both NPM and Docker Hub
5. **Success** → all done, or **Failure** → creates issue and triggers retry

### Workflow Files

- `.github/workflows/release.yml` - Main release workflow
- `.github/workflows/docker-publish.yml` - Manual/fallback Docker publishing
- `.github/workflows/verify-release.yml` - Verification and retry logic

## Common Issues and Solutions

### 1. Docker Publishing Failed (NPM Succeeded)

**Symptoms:**

- NPM has the new version
- Docker Hub is missing the version
- Verification workflow creates an issue

**Causes:**

- Docker Hub credentials expired
- Docker build failure (platform issues, Dockerfile errors)
- Network timeouts
- Docker Hub rate limiting

**Solutions:**

#### Option A: Automatic Retry (Recommended)

The verification workflow should automatically trigger a retry. Check the workflow run logs.

#### Option B: Manual Workflow Trigger

```bash
# Replace v2.3.0 with your version
gh workflow run docker-publish.yml -f tag=v2.3.0 -f push=true
```

#### Option C: Local Manual Build (Emergency)

```bash
# Use the provided script
./scripts/manual-docker-publish.sh 2.3.0

# Or manually:
docker build --platform linux/amd64,linux/arm64 \
  --tag docdyhr/mcp-wordpress:2.3.0 \
  --tag docdyhr/mcp-wordpress:latest \
  --push .
```

### 2. NPM Publishing Failed

**Symptoms:**

- GitHub release created but NPM doesn't have the version
- Semantic-release logs show NPM errors

**Causes:**

- NPM_TOKEN expired or invalid
- Package.json issues
- NPM registry issues

**Solutions:**

```bash
# Verify you're logged in
npm whoami

# Manual publish
npm publish

# Or with explicit registry
npm publish --registry https://registry.npmjs.org
```

### 3. Both NPM and Docker Failed

**Causes:**

- GitHub secrets issues (NPM_TOKEN, DOCKER_USERNAME, DOCKER_PASSWORD)
- Semantic-release configuration problems
- Build/test failures

**Solutions:**

1. **Check secrets in GitHub repository settings**
2. **Verify semantic-release configuration**
3. **Run release dry-run locally:**

   ```bash
   npm run release:dry
   ```

### 4. Version Already Exists

**Symptoms:**

- "Version 2.3.0 already exists" errors

**Solutions:**

For NPM:

```bash
# You cannot overwrite existing versions
# You need to bump the version and release again
npm version patch  # or minor/major
```

For Docker:

```bash
# You can overwrite Docker tags
docker build --platform linux/amd64,linux/arm64 \
  --tag docdyhr/mcp-wordpress:2.3.0 --push .
```

## Verification

### Check NPM Publication

```bash
# Check if version exists
npm view mcp-wordpress@2.3.0

# Check latest version
npm view mcp-wordpress version

# View all versions
npm view mcp-wordpress versions --json
```

### Check Docker Hub Publication

```bash
# Pull the image
docker pull docdyhr/mcp-wordpress:2.3.0

# Check manifest
docker manifest inspect docdyhr/mcp-wordpress:2.3.0

# API check
curl -s https://hub.docker.com/v2/repositories/docdyhr/mcp-wordpress/tags | jq '.results[] | select(.name == "2.3.0")'
```

## Emergency Manual Release Process

If all automated processes fail:

1. **Prepare the release:**

   ```bash
   git checkout main
   git pull origin main
   npm ci
   npm run build
   npm test
   ```

2. **Manual NPM publish:**

   ```bash
   npm publish
   ```

3. **Manual Docker publish:**

   ```bash
   ./scripts/manual-docker-publish.sh
   ```

4. **Create GitHub release:**

   ```bash
   gh release create v2.3.0 --title "v2.3.0" --notes "Manual release"
   ```

## Prevention

### Regular Maintenance

1. **Rotate secrets annually:**

   - NPM_TOKEN
   - DOCKER_USERNAME/DOCKER_PASSWORD

2. **Test publishing process:**

   ```bash
   npm run release:dry
   ```

3. **Monitor workflow success rates**

### Monitoring

- **GitHub Actions** - Check workflow success rates
- **NPM** - Monitor download stats for version gaps
- **Docker Hub** - Check pull statistics
- **Verification workflow** - Reviews automated issue creation

## Contact

For persistent issues:

1. Check existing GitHub issues with label `publishing-failure`
2. Create new issue with publishing logs
3. Contact maintainers if critical
