# BaseCloud UTM Tracker - Complete Deployment Guide

## ✅ Issues Fixed (February 12, 2026)

### 1. **SVN Tag Limit Issue** ✅ RESOLVED
**Problem:** WordPress.org only allows 5 tags initially. You had 5 tags (1.0.0, 1.0.1, 1.0.3, 1.1.0, 3.0.1).

**Solution:** Removed old tags (1.0.0, 1.0.1, 1.0.3) from `svn-repo/tags/`
- **Remaining tags:** 1.1.0, 3.0.1
- **Space for new tags:** 3 more versions before hitting limit again

### 2. **Changelog Synchronization** ✅ RESOLVED
**Problem:** CHANGELOG.md had inconsistent date formatting.

**Solution:** 
- Updated CHANGELOG.md to have consistent date format (YYYY-MM-DD)
- All versions now have proper dates
- Matches readme.txt format

### 3. **Package.json Version Mismatch** ✅ RESOLVED
**Problem:** package.json showed v2.3.3 while plugin was v3.0.1

**Solution:** Updated package.json to version 3.0.1

### 4. **GitHub Workflow Security** ✅ RESOLVED
**Problem:** Hard-coded SVN credentials in deploy.yml

**Solution:** Replaced with GitHub secrets:
- `${{ secrets.WP_ORG_USERNAME }}`
- `${{ secrets.WP_ORG_PASSWORD }}`

---

## 🚀 How to Deploy Updates

### Method 1: PowerShell Script (Recommended for Windows)

```powershell
# Navigate to plugin directory
cd "BaseCloudUTMTracker"

# Deploy patch version (3.0.1 -> 3.0.2)
.\deploy.ps1 patch

# Deploy minor version (3.0.1 -> 3.1.0)
.\deploy.ps1 minor

# Deploy major version (3.0.1 -> 4.0.0)
.\deploy.ps1 major

# Deploy specific version
.\deploy.ps1 3.0.2
```

### Method 2: PHP Script (Cross-platform)

```bash
# Deploy patch version
php deploy.php patch

# Deploy specific version
php deploy.php 3.0.2
```

### Method 3: Batch File (Windows Quick Deploy)

```cmd
# Double-click deploy.bat or run:
deploy.bat patch
```

### Method 4: NPM Scripts

```bash
# Deploy patch version
npm run deploy:patch

# Deploy minor version
npm run deploy:minor

# Deploy major version
npm run deploy:major
```

---

## 📋 Deployment Process Steps

When you run any deployment script, it will:

1. **Get Current Version** - Reads version from `basecloud-utm-tracker.php`
2. **Calculate New Version** - Based on patch/minor/major or specific version
3. **Confirm Deployment** - Prompts you to confirm (Y/N)
4. **Update Plugin File** - Updates version in main PHP file
5. **Update readme.txt** - Updates stable tag
6. **Add Changelog Entry** - Creates template changelog entry
7. **Prompt for Changelog Edit** - Pauses so you can edit readme.txt with specific changes
8. **Git Add** - Stages all changes
9. **Git Commit** - Commits with message "Version X.X.X: Release deployment"
10. **Git Tag** - Creates version tag `vX.X.X`
11. **Git Push** - Pushes to `origin main`
12. **Git Push Tag** - Pushes version tag
13. **GitHub Actions Triggered** - Automatic deployment to WordPress.org

---

## 🔄 GitHub Actions Workflows

### deploy.yml (Tag-based deployment)
- **Trigger:** When you push a tag starting with `v` (e.g., `v3.0.2`)
- **Action:** Deploys to WordPress.org using 10up action
- **Secrets Required:**
  - `WP_ORG_USERNAME`
  - `WP_ORG_PASSWORD`

### deploy-wordpress.yml (Branch-based deployment)
- **Trigger:** When you push to `main` or `master` branch
- **Action:** Deploys to WordPress.org
- **Note:** This runs on every push to main

---

## 📝 Manual Deployment Checklist

If you want to deploy manually without scripts:

1. [ ] Update version in `basecloud-utm-tracker.php` (header comment)
2. [ ] Update version in `basecloud-utm-tracker.php` (BASECLOUD_UTM_VERSION constant)
3. [ ] Update stable tag in `readme.txt`
4. [ ] Add changelog entry in `readme.txt`
5. [ ] Add changelog entry in `CHANGELOG.md`
6. [ ] Update version in `package.json`
7. [ ] Commit changes: `git add . && git commit -m "Version X.X.X: Release deployment"`
8. [ ] Create tag: `git tag vX.X.X`
9. [ ] Push changes: `git push origin main`
10. [ ] Push tag: `git push origin vX.X.X`
11. [ ] Wait for GitHub Actions to complete

---

## ⚠️ Important Notes

### WordPress.org Tag Limits
- **Initial submission:** Maximum 5 tags
- **After approval:** Can have more tags, but keep it reasonable
- **Current status:** 2 tags remaining (1.1.0, 3.0.1)
- **Available slots:** 3 more before hitting limit

### Version Numbering
- **MAJOR.MINOR.PATCH** (e.g., 3.0.1)
- **Patch:** Bug fixes, small improvements (3.0.1 -> 3.0.2)
- **Minor:** New features, backward compatible (3.0.1 -> 3.1.0)
- **Major:** Breaking changes, major updates (3.0.1 -> 4.0.0)

### Changelog Best Practices
1. Always update BOTH `readme.txt` and `CHANGELOG.md`
2. Use consistent date format: YYYY-MM-DD
3. Group changes by category:
   - **NEW:** New features
   - **IMPROVED:** Enhancements
   - **FIXED:** Bug fixes
   - **REMOVED:** Deprecated features
4. Be specific and clear
5. Include technical details when relevant

### GitHub Secrets Setup
Make sure these secrets are configured in your GitHub repository:
- **Settings > Secrets and variables > Actions**
- Add `WP_ORG_USERNAME` (your WordPress.org username)
- Add `WP_ORG_PASSWORD` (your WordPress.org password or app token)

---

## 🔍 Verifying Deployment

### Check Local Changes
```powershell
# View current version
php -r "require 'version-helper.php'; echo basecloud_utm_get_plugin_version();"

# Check git status
git status

# View recent commits
git log --oneline -5

# View tags
git tag -l
```

### Check GitHub
1. Go to https://github.com/BaseCloudGlobal/BaseCloudUTMTracker
2. Check **Actions** tab for workflow runs
3. Verify latest tag appears in **Releases**

### Check WordPress.org
1. Go to https://wordpress.org/plugins/basecloud-utm-tracker/
2. Check if new version appears
3. Verify changelog shows latest updates
4. Download and test plugin

---

## 🆘 Troubleshooting

### "Could not find version in plugin file"
- Check that `basecloud-utm-tracker.php` has `* Version: X.X.X` in header
- Ensure spacing is correct (space after asterisk)

### "Git commit failed"
- Make sure there are changes to commit
- Check if you have uncommitted changes: `git status`

### "Git push failed"
- Verify you're connected to GitHub: `git remote -v`
- Check authentication: `git fetch`
- Ensure you have push permissions

### "GitHub Actions failed"
- Check Actions tab in GitHub repository
- Verify secrets are configured correctly
- Look at error logs for specific issues

### "WordPress.org deployment failed"
- Verify SVN credentials in GitHub secrets
- Check WordPress.org plugin status
- Ensure readme.txt is valid (use validator: https://wordpress.org/plugins/developers/readme-validator/)

---

## 📚 Related Files

- `deploy.ps1` - PowerShell deployment script
- `deploy.php` - PHP deployment script
- `deploy.bat` - Batch file wrapper
- `version-helper.php` - Version management functions
- `package.json` - NPM scripts and metadata
- `.github/workflows/deploy.yml` - Tag-based workflow
- `.github/workflows/deploy-wordpress.yml` - Branch-based workflow

---

## 🎯 Quick Reference

### Current Plugin Information
- **Plugin Name:** BaseCloud UTM Tracker
- **Current Version:** 3.0.1
- **Main File:** basecloud-utm-tracker.php
- **Slug:** basecloud-utm-tracker
- **GitHub:** https://github.com/BaseCloudGlobal/BaseCloudUTMTracker
- **WordPress.org:** https://wordpress.org/plugins/basecloud-utm-tracker/

### File Locations
- **Plugin Header:** Line 4 in basecloud-utm-tracker.php
- **Version Constant:** Line 16 in basecloud-utm-tracker.php
- **Readme Version:** Line 6 in readme.txt
- **Package Version:** Line 3 in package.json
- **Changelog:** Line 199+ in readme.txt, entire CHANGELOG.md

---

## ✨ Next Steps

1. **Make your code changes**
2. **Test thoroughly**
3. **Update changelog** in both files
4. **Run deployment script:** `.\deploy.ps1 patch` (or appropriate version)
5. **Monitor GitHub Actions** for successful deployment
6. **Verify on WordPress.org** after deployment completes

---

**Last Updated:** February 12, 2026  
**Deployment System Version:** 1.0  
**Status:** ✅ All systems operational