# BaseCloud UTM Tracker - Deployment Guide

This guide explains the streamlined deployment system that eliminates the need to manually update version numbers in multiple files.

## 🚀 Quick Deployment Options

### Option 1: PowerShell Script (Recommended for Windows)
```powershell
# Patch version (2.3.0 → 2.3.1)
.\deploy.ps1 patch

# Minor version (2.3.0 → 2.4.0)
.\deploy.ps1 minor

# Major version (2.3.0 → 3.0.0)
.\deploy.ps1 major

# Specific version
.\deploy.ps1 2.3.5
```

### Option 2: Batch File (Simplest)
```cmd
# Double-click deploy.bat or run:
deploy.bat patch
deploy.bat minor
deploy.bat major
```

### Option 3: NPM Scripts
```bash
# Install npm first (if not already done)
npm install

# Deploy patch version
npm run deploy

# Deploy minor version
npm run deploy:minor

# Deploy major version
npm run deploy:major

# Check current version
npm run version:get
```

### Option 4: PHP Script (Cross-platform)
```bash
php deploy.php patch
php deploy.php minor
php deploy.php major
php deploy.php 2.3.5
```

## 📋 What Each Script Does

1. **Updates version number** in `basecloud-utm-tracker.php`
2. **Updates stable tag** in `readme.txt`
3. **Prompts for changelog** entry (manual step)
4. **Commits changes** to git
5. **Creates version tag** (e.g., v2.3.1)
6. **Pushes to repository** and triggers GitHub workflow
7. **Automatically deploys** to WordPress.org

## 🔧 Version Management System

### Single Source of Truth
- **Plugin version** is defined only in `basecloud-utm-tracker.php`
- **All scripts** read from this single source
- **No more manual updates** in multiple files

### Version Helper Functions
The `version-helper.php` file provides:
- `basecloud_utm_get_plugin_version()` - Get current version
- `basecloud_utm_update_readme_version()` - Update readme.txt
- `basecloud_utm_bump_version($type)` - Calculate next version

## 🎯 Deployment Workflow

```
1. Run deployment script
   ↓
2. Script updates version numbers automatically
   ↓
3. You add changelog entry (manual)
   ↓
4. Script commits & tags automatically
   ↓
5. GitHub workflow triggers
   ↓
6. Plugin deploys to WordPress.org
```

## 🛠️ Manual Version Update (if needed)

If you need to manually update versions:

1. **Update plugin file:**
   ```php
   * Version:           2.3.1
   define('BASECLOUD_UTM_VERSION', '2.3.1');
   ```

2. **Update readme.txt:**
   ```
   Stable tag: 2.3.1
   ```

3. **Update changelog in readme.txt**

## 📝 Changelog Format

When prompted to update the changelog, use this format in `readme.txt`:

```markdown
== Changelog ==

= 2.3.1 =
**Release Update**

• Fixed: Description of bug fixes
• Enhanced: Description of improvements
• Added: Description of new features

= 2.3.0 =
**Previous Release**
...
```

## 🔄 GitHub Workflow

The `.github/workflows/deploy.yml` file automatically:
- Triggers on git tag push (e.g., `v2.3.1`)
- Checks out the code
- Deploys to WordPress.org SVN
- Updates plugin assets (icons, banners, screenshots)

### Workflow File Location
`.github/workflows/deploy.yml`

### SVN Credentials
Stored as GitHub repository secrets:
- `SVN_USERNAME`: basecloud
- `SVN_PASSWORD`: [Stored in GitHub Secrets]

## 📦 Plugin Information
- **Plugin Slug:** basecloud-utm-tracker
- **WordPress.org URL:** https://wordpress.org/plugins/basecloud-utm-tracker/
- **SVN Repository:** https://plugins.svn.wordpress.org/basecloud-utm-tracker
- **GitHub Repository:** https://github.com/BaseCloudGlobal/BaseCloudUTMTracker
- **Current Version:** 2.3.0

## 🖼️ Managing Assets

Plugin assets (icons, banners, screenshots) are stored in the `assets/` directory and automatically deployed by the GitHub workflow.

### Required Asset Files:
- `icon-128x128.png` - Small icon (128x128px)
- `icon-256x256.png` - Large icon (256x256px)
- `banner-772x250.png` - Standard banner
- `banner-1544x500.png` - Retina banner
- `screenshot-1.png` - First screenshot
- `screenshot-2.png` - Second screenshot

### Asset Guidelines:
- Use PNG format for all images
- Follow WordPress.org naming conventions
- Optimize images for web (use compression)
- Update assets by committing to the `assets/` directory

## 🐛 Troubleshooting

### Version not updating
- Ensure you're in the correct directory
- Check file permissions
- Verify git repository is clean

### Git push fails
- Check you're on the correct branch (`local`)
- Ensure you have push permissions
- Verify remote repository is accessible

### WordPress.org not updating
- Check GitHub Actions status: https://github.com/BaseCloudGlobal/BaseCloudUTMTracker/actions
- Verify tag was pushed: `git tag -l`
- Check SVN credentials in GitHub Secrets
- Review WordPress.org plugin dashboard

### Deployment fails mid-process
- Reset local changes: `git reset --hard HEAD`
- Delete the tag: `git tag -d v2.3.1`
- Fix the issue and try again

## 📚 Additional Resources

- [WordPress Plugin Handbook](https://developer.wordpress.org/plugins/)
- [WordPress.org SVN Guide](https://developer.wordpress.org/plugins/wordpress-org/how-to-use-subversion/)
- [GitHub Actions Documentation](https://docs.github.com/en/actions)

## 🔐 Security Notes

- Never commit SVN password to repository
- Keep GitHub secrets secure
- Use environment variables for sensitive data
- Review deployment logs for exposed credentials

## ✅ Pre-Deployment Checklist

Before running deployment:
- [ ] All changes committed and tested
- [ ] Version number is correct
- [ ] Changelog is updated with meaningful entries
- [ ] No sensitive data in code
- [ ] Code follows WordPress coding standards
- [ ] Plugin tested on latest WordPress version
- [ ] Compatibility with form plugins verified

## 📞 Support

For issues or questions:
- GitHub Issues: https://github.com/BaseCloudGlobal/BaseCloudUTMTracker/issues
- Email: support@basecloudglobal.com

   - `icon-256x256.png` - Large icon  
   - `banner-772x250.png` - Header banner
   - `banner-1544x500.png` - High-res header banner
   - `screenshot-1.png`, `screenshot-2.png`, etc. - Screenshots

2. Copy to the assets directory:
```bash
copy assets\*.png svn-repo\assets\
```

3. Commit assets:
```bash
cd svn-repo
svn add assets\*
svn commit -m "Add plugin assets"
```

## Troubleshooting

### SVN Authentication
If prompted for credentials:
- Username: `basecloud`
- Password: Use your WordPress.org password

### SVN Conflicts
If there are conflicts during update:
```bash
svn resolve --accept working svn-repo\trunk\filename
```

### Plugin Not Updating
- Check that version numbers match in both plugin file and readme.txt
- Ensure the stable tag in readme.txt is updated
- Wait up to 15 minutes for WordPress.org to process the update

## Support
- WordPress.org Plugin Directory: https://wordpress.org/support/plugin/basecloud-utm-tracker/
- BaseCloud Support: Contact through official channels