# WordPress.org Deployment Guide

## Overview

WordPress.org deployment is **completely separate** from the versioning and release process. This allows you to:

✅ Test versioning without accidentally deploying  
✅ Create GitHub releases independently  
✅ Deploy to WordPress.org only when you're ready  
✅ Run dry runs to test deployment without publishing  

## Prerequisites

Before you can deploy to WordPress.org, you need:

1. **WordPress.org Plugin Account**
   - Your plugin must be approved on WordPress.org
   - You must have commit access to the plugin

2. **GitHub Secrets**
   - `WP_ORG_USERNAME` - Your WordPress.org username
   - `WP_ORG_PASSWORD` - Your WordPress.org password (or app password)

### Setting Up GitHub Secrets

1. Go to your repository on GitHub
2. Click **Settings** → **Secrets and variables** → **Actions**
3. Click **New repository secret**
4. Add both secrets:
   - Name: `WP_ORG_USERNAME`, Value: your username
   - Name: `WP_ORG_PASSWORD`, Value: your password

## Deployment Process

### Step 1: Create a Release First

Before deploying to WordPress.org, you should have a GitHub release:

```bash
1. Use "Release - Create" workflow
2. Merge the release PR
3. Verify the GitHub release was created
4. Download and test the plugin zip locally
```

### Step 2: Deploy to WordPress.org

#### Option A: Dry Run (Recommended First)

Test the deployment without actually publishing:

1. Go to **Actions** → **Deploy - WordPress.org**
2. Click **Run workflow**
3. Enter the release tag (e.g., `v1.0.0`)
4. ✅ Check **"Dry run"** 
5. Click **Run workflow**
6. Review the output to ensure everything works

#### Option B: Actual Deployment

After confirming with a dry run:

1. Go to **Actions** → **Deploy - WordPress.org**
2. Click **Run workflow**
3. Enter the release tag (e.g., `v1.0.0`)
4. ❌ Uncheck **"Dry run"**
5. Click **Run workflow**
6. Wait for deployment to complete
7. Verify at: https://wordpress.org/plugins/recast-paywall/

## Workflow Inputs

### Release Tag (Required)

The git tag to deploy. Must match format: `vX.Y.Z`

Examples:
- ✅ `v1.0.0` - Valid
- ✅ `v2.5.3` - Valid
- ❌ `1.0.0` - Invalid (missing 'v')
- ❌ `v1.0` - Invalid (must be X.Y.Z)

### Dry Run (Optional)

- **Checked**: Tests deployment without publishing
- **Unchecked**: Actually deploys to WordPress.org

**Best Practice**: Always run with dry run first!

## What Gets Deployed

The workflow:

1. Checks out the specified git tag
2. Installs PHP dependencies (production only)
3. Removes development files:
   - `tests/`
   - `vendor/` (then reinstalls without dev deps)
   - `.git/`, `.github/`
   - `.editorconfig`, `.gitignore`
   - `composer.lock`
   - `package.json`, `package-lock.json`
   - ESLint/Prettier configs

4. Deploys to WordPress.org SVN:
   - Updates `trunk/` with new code
   - Creates version tag (e.g., `tags/1.0.0/`)

## Validation & Safety

### Automatic Validation

The workflow automatically:

✅ Validates tag format (must be `vX.Y.Z`)  
✅ Checks for required credentials  
✅ Warns about pre-release versions  
✅ Prevents deployment in dry run mode  

### Pre-release Versions

Tags with hyphens are considered pre-releases:

- `v1.0.0-beta.1` - Pre-release (warning shown)
- `v1.0.0-rc.2` - Pre-release (warning shown)
- `v1.0.0` - Stable release

## Troubleshooting

### Error: Invalid release tag format

**Problem**: Tag doesn't match `vX.Y.Z` format

**Solution**: 
```bash
# Correct format
v1.0.0  ✅
v2.5.3  ✅

# Incorrect format
1.0.0   ❌ (add 'v' prefix)
v1.0    ❌ (needs patch version)
```

### Error: WordPress.org credentials not set

**Problem**: GitHub secrets are missing

**Solution**:
1. Go to repository Settings → Secrets
2. Add `WP_ORG_USERNAME` and `WP_ORG_PASSWORD`
3. Re-run the workflow

### Error: SVN authentication failed

**Problem**: Credentials are incorrect or expired

**Solution**:
1. Update the GitHub secrets with correct credentials
2. Consider using an [application password](https://wordpress.org/support/article/using-application-passwords/) instead of your main password
3. Verify you have commit access to the plugin

### Warning: Tag already exists in SVN

**Behavior**: The workflow will remove the existing tag and create a new one

**This is normal** if you're re-deploying the same version.

## Testing Deployments

### Local Testing

Before deploying to WordPress.org, test locally:

1. Download the plugin zip from GitHub release
2. Install on a test WordPress site
3. Test all functionality
4. Verify version numbers are correct

### Dry Run Testing

Always use dry run first:

```bash
1. Go to Actions → Deploy to WordPress.org
2. Enter tag: v1.0.0
3. ✅ Check "Dry run"
4. Review output for any errors
5. If successful, run again without dry run
```

## Deployment Checklist

Before deploying to WordPress.org:

- [ ] GitHub release created successfully
- [ ] Plugin zip downloaded and tested locally
- [ ] All tests passing in CI
- [ ] Version numbers correct in all files
- [ ] readme.txt changelog updated
- [ ] Screenshots updated (if applicable)
- [ ] Dry run completed successfully
- [ ] WordPress.org credentials configured
- [ ] Ready to publish!

## Post-Deployment

After successful deployment:

1. **Verify on WordPress.org**
   - Visit: https://wordpress.org/plugins/recast-paywall/
   - Check version number is correct
   - Verify changelog appears correctly
   - Test download link

2. **Test Installation**
   - Install on a clean WordPress site
   - Verify auto-updates work
   - Test all features

3. **Monitor**
   - Watch for support requests
   - Check error reports
   - Monitor download stats

## Comparison: Versioning vs. Deployment

| Action | Where It Happens | Automatic? |
|--------|------------------|------------|
| Version bump | GitHub (sync script) | ✅ Yes (via workflows) |
| Create release | GitHub | ✅ Yes (when PR merged) |
| Build plugin zip | GitHub Actions | ✅ Yes |
| Upload to GitHub | GitHub Releases | ✅ Yes |
| Deploy to WP.org | WordPress.org SVN | ❌ No (manual trigger) |

**Key Point**: Everything is automatic EXCEPT WordPress.org deployment!

## Examples

### Example 1: First Release

```bash
# 1. Create release
Actions → Release - Create
Version: 1.0.0
Type: major

# 2. Review and merge PR
# 3. GitHub release created automatically

# 4. Test deployment (dry run)
Actions → Deploy to WordPress.org
Tag: v1.0.0
Dry run: ✅ YES
[Run workflow]

# 5. Review output, then deploy for real
Actions → Deploy to WordPress.org
Tag: v1.0.0
Dry run: ❌ NO
[Run workflow]

# 6. Verify at WordPress.org
Visit: https://wordpress.org/plugins/recast-paywall/
```

### Example 2: Bug Fix Release

```bash
# 1. Fix bug on develop branch
git checkout develop
git commit -m "fix: resolve critical security issue"

# 2. Create patch release
Actions → Release - Create
Version: 1.0.1
Type: patch

# 3. Merge PR (emergency fast-track)

# 4. Deploy immediately to WP.org
Actions → Deploy to WordPress.org
Tag: v1.0.1
Dry run: ❌ NO (skip dry run for urgent fixes)
[Run workflow]
```

### Example 3: Beta Testing

```bash
# 1. Create pre-release
Actions → Release - Create
Version: 2.0.0-beta.1
Type: major

# 2. Merge PR
# GitHub release created (marked as pre-release)

# 3. Do NOT deploy to WordPress.org
# Instead, share GitHub release link with beta testers

# 4. After testing, create stable release
Actions → Release - Create
Version: 2.0.0
Type: major

# 5. Then deploy to WordPress.org
Actions → Deploy to WordPress.org
Tag: v2.0.0
Dry run: ❌ NO
[Run workflow]
```

## Security Best Practices

1. **Use Application Passwords**
   - Create at: https://wordpress.org/support/article/using-application-passwords/
   - More secure than main password
   - Can be revoked independently

2. **Limit Access**
   - Only trusted maintainers should have WP.org credentials
   - GitHub secrets are only accessible to those with repo admin access

3. **Verify Before Deploying**
   - Always test locally first
   - Use dry run mode
   - Review all changes in the release

4. **Keep Secrets Updated**
   - Rotate passwords periodically
   - Update secrets if team members leave
   - Use strong, unique passwords

## Need Help?

- **WordPress.org Plugin Handbook**: https://developer.wordpress.org/plugins/wordpress-org/
- **SVN Documentation**: https://developer.wordpress.org/plugins/wordpress-org/how-to-use-subversion/
- **Application Passwords**: https://wordpress.org/support/article/using-application-passwords/

## Summary

✅ **Versioning**: Automatic via GitHub workflows  
✅ **GitHub Releases**: Automatic when PR merged  
✅ **Plugin Builds**: Automatic  
❌ **WordPress.org Deploy**: Manual (you control when)  

This separation gives you:
- 🧪 Safe testing environment
- 🎯 Control over public releases
- 🛡️ Protection against accidental deployments
- 🚀 Confidence in your release process

**You can now test versioning as much as you want without worrying about deploying to WordPress.org!** 🎉

