# WordPress Plugin SVN Guide – Short Reference

Prerequisites

  • TortoiseSVN installed on Windows
  • WordPress.org account with plugin approval
  • Plugin files ready for upload

Initial Setup & First Upload

Step 1: Get Your SVN Repository URL

Your plugin’s SVN URL follows this format:

https://plugins.svn.wordpress.org/[your-plugin-name]/

Step 2: Initial SVN Checkout

  1. Create/navigate to your working folder
  2. Right-click → SVN Checkout
  3. URL: https://plugins.svn.wordpress.org/[plugin-name]/
  4. Checkout Depth: Fully recursive, HEAD revision
  5. Enter WordPress.org credentials when prompted

This creates the standard structure:

  • assets/ – Plugin directory images (banners, icons, screenshots)
  • trunk/ – Development version
  • tags/ – Released versions

Step 3: Copy Your Files

Assets folder:

  • Copy banner images, icons, screenshots to assets/

Plugin code:

  • Copy all plugin files to trunk/

Step 4: Add Files to SVN

  1. Right-click main plugin folder → TortoiseSVN → Add
  2. Select all new files/folders → OK
  3. If “nothing to add” appears, check: Right-click → TortoiseSVN → Check for modifications

Step 5: Commit to Trunk

  1. Right-click main plugin folder → SVN Commit
  2. Commit message: “Initial plugin upload – version X.X.X”
  3. Ensure all files are checked → OK

Step 6: Create Version Tag

  1. Right-click trunk folder → TortoiseSVN → Branch/Tag
  2. To path: Change from /trunk to /tags/X.X.X
  3. Create copy in repository from: HEAD revision in repository
  4. Log message: “Tagging version X.X.X”
  5. Click OK

Plugin Updates

For Assets Only (No Version Change)

Use case: Update banners, icons, screenshots without releasing new version

  1. Replace files in local assets/ folder
  2. Right-click main plugin folder → SVN Commit
  3. Commit message: “Updated plugin assets”
  4. Click OK

Result: Changes appear immediately on plugin page, no user notifications

For Plugin Updates (New Version)

Use case: Code changes requiring new version

  1. Update version numbers in:
    • Main plugin file header
    • readme.txt stable tag
  2. Modify code in trunk/ folder
  3. Right-click main plugin folder → SVN Commit
  4. Commit message: “Update to version X.X.X”
  5. Click OK
  6. Right-click trunk folder → TortoiseSVN → Branch/Tag
  7. To path: /tags/X.X.X
  8. Log message: “Tagging version X.X.X”
  9. Click OK

Result: Users get update notifications, new version available for download

File Structure Reference

your-plugin/
├── .svn/                    (SVN metadata - don't touch)
├── assets/                  (Plugin directory assets)
│   ├── banner-1544x500.png  (Large banner)
│   ├── banner-772x250.png   (Small banner)
│   ├── icon-128x128.png     (Plugin icon - small)
│   ├── icon-256x256.png     (Plugin icon - large)
│   ├── screenshot-1.png     (Screenshots for plugin page)
│   └── screenshot-N.png     (Up to 10 screenshots)
├── tags/                    (Released versions)
│   ├── 1.0.0/              (Snapshot of version 1.0.0)
│   ├── 1.0.1/              (Snapshot of version 1.0.1)
│   └── X.X.X/              (Each tagged version)
└── trunk/                   (Development/current version)
    ├── your-plugin.php     (Main plugin file)
    ├── readme.txt          (Plugin description/changelog)
    ├── assets/             (Plugin's internal assets)
    ├── includes/           (Plugin code files)
    ├── languages/          (Translation files)
    └── uninstall.php       (Cleanup code)

Important Notes

Version Numbers

  • Plugin header: Must match readme.txt stable tag
  • readme.txt: Update stable tag for each release
  • Semantic versioning: Use X.Y.Z format (1.0.0, 1.0.1, 1.1.0)

Auto-Updates

  • Plugins installed from WordPress.org get automatic update notifications
  • Manually installed plugins may not receive updates unless headers match exactly
  • Plan plugin structure for WordPress.org compatibility from the start

Common Commit Messages

  • "Initial plugin upload - version X.X.X"
  • "Update to version X.X.X"
  • "Updated plugin assets"
  • "Bug fixes for version X.X.X"
  • "Tagging version X.X.X"

Troubleshooting

  • “Nothing to add”: Use “Check for modifications” to see file status
  • Credentials: Use WordPress.org username/password
  • Files not showing: Ensure proper file permissions and no .svnignore conflicts
  • Tag creation fails: Ensure trunk is committed first

Quick Reference Commands

ActionSteps
First uploadCheckout → Copy files → Add → Commit → Tag
Update assetsReplace files → Commit
Update pluginModify code → Update versions → Commit → Tag
Check statusRight-click → TortoiseSVN → Check for modifications

For WordPress Compatibility Updates (No Code Changes)

Use case: Update “Tested up to” field without version bump

Option 1: Update Existing Tag (Recommended)

  1. Update locally: Change “Tested up to” in readme.txt (keep same version)
  2. Commit to trunk: Message: “Updated WordPress compatibility to 6.X.X”
  3. Update existing tag:
    • Right-click trunk → TortoiseSVN → Branch/Tag
    • To path: /tags/X.X.X (same existing tag number)
    • Message: “Updated WordPress compatibility for X.X.X”

Result: Same version, updated compatibility, no user notifications

Option 2: New Version Tag

  1. Update locally: Change “Tested up to” and bump version number
  2. Commit and tag as normal plugin update

Result: New version, users get update notifications

Troubleshooting Common Issues

“Nothing to Add” Error

  • Cause: Files already tracked or ignored
  • Solution: Right-click → TortoiseSVN → Check for modifications
  • Look for: Files with “?” (unversioned) status to add manually

Authentication Issues

  • Use: WordPress.org username and password (not email)
  • Reset: If forgotten, use WordPress.org password reset
  • Cache: TortoiseSVN may cache credentials – clear if needed

Tag Already Exists Error

  • Cause: Trying to create tag that already exists
  • Solution: Delete existing tag first, or use different version number
  • Alternative: Update existing tag (overwrites it)

Files Not Showing in Commit

  • Check: File permissions and ownership
  • Verify: No .svnignore or global ignore patterns blocking files
  • Solution: Add files manually via “Add” dialog

Best Practices

  1. Test locally before committing to SVN
  2. Update version numbers before tagging (except compatibility updates)
  3. Write clear commit messages
  4. Keep assets optimized (reasonable file sizes)
  5. Validate readme.txt before upload
  6. Create tags for every release (enables rollbacks)
  7. Don’t commit unnecessary files (.DS_Store, node_modules, etc.)
  8. Regular compatibility updates keep plugin active in directory
  9. Use semantic versioning (X.Y.Z format consistently)
  10. Backup before major changes (though SVN provides history)

WordPress.org Timeline

  • Assets: Update immediately
  • Plugin approval: Initial review (varies)
  • Updates: Available immediately after tagging
  • Directory listing: Updates within hours
  • Compatibility updates: Show immediately on plugin page