DEV Community

Cover image for Mastering WordPress Plugin SVN Updates: A Beginner's Guide to Smooth Releases
Shahibur Rahman
Shahibur Rahman

Posted on

Mastering WordPress Plugin SVN Updates: A Beginner's Guide to Smooth Releases

#wordpress #svn #plugins #tutorial

Publishing your initial release to the WordPress.org plugin directory is a huge milestone. But as any developer knows, the launch is just the beginning. The real work starts when you need to roll out bug fixes, push feature updates, and manage visual storefront assets. For many developers, performing WordPress Plugin SVN Updates can feel like navigating a minefield of potential errors—from broken tags and untracked files to stuck working copies and CDN caching delays.

Whether you're pushing version 1.0.8 or just refreshing your store banners, this guide provides a streamlined, step-by-step workflow for updating and maintaining your WordPress plugin smoothly and without stress.

The Core Concept: How WordPress.org SVN Works

Unlike Git, where branches and tags are lightweight references, SVN handles directory structures directly inside your working copy:

  • /trunk: Contains your active development code. WordPress.org uses this as the primary reference for your plugin's main page and source code.
  • /tags/X.X.X: An immutable snapshot of a specific released version (e.g., tags/1.0.7). Never edit files directly inside a tag folder. Always update trunk first and copy it over to a new tag.
  • /assets: Located at the root level of your repo (outside trunk). Holds storefront display images like banners, icons, and screenshots.

Step 1: Prepare Your Local Version Changes

Before touching SVN commands, prepare your updated plugin code locally within your working copy:

Update Plugin Headers

Open your main plugin PHP file (e.g., my-sample-plugin.php) and increment the version header:

/*
 * Plugin Name: My Sample Plugin
 * Plugin URI: https://example.com/my-sample-plugin
 * Description: A sample WordPress plugin.
 * Version: 1.0.8
 * Author: Your Name
 * Author URI: https://example.com/your-profile
 */
Enter fullscreen mode Exit fullscreen mode

Update readme.txt

Open trunk/readme.txt and ensure both the header and stable tag match your new version:

=== My Sample Plugin ===
Contributors: your_username
Tags: plugin, sample, wordpress
Requires at least: 5.0
Tested up to: 6.0
Stable tag: 1.0.8
License: GPLv2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html

Description: This is a sample description for your WordPress plugin.

== Changelog ==

= 1.0.8 =
* Bug fix: Resolved issue with widget display.
* New feature: Added option for custom post types.

= 1.0.7 =
* Initial release.
Enter fullscreen mode Exit fullscreen mode

Crucial: WordPress.org reads trunk/readme.txt to determine which version is marked as the official active release for users!

Step 2: Check Local Repository Status

Open your terminal, navigate to your root SVN directory, and inspect your working copy:

cd /path/to/your-plugin-svn-repo
svn status
Enter fullscreen mode Exit fullscreen mode

Understanding the status symbols:

  • M (Modified): Existing tracked files that you edited.
  • A (Added): New files staged to be tracked.
  • ? (Untracked): Files SVN sees locally but isn't tracking yet (e.g., local test scripts or build files). These generally should not be committed.

Step 3: Create the New Release Tag

To package your updated code from trunk into a dedicated version release:

svn copy trunk tags/1.0.8
Enter fullscreen mode Exit fullscreen mode

This creates a new snapshot directory tags/1.0.8/ containing an exact replica of your updated trunk.

Step 4: Updating Storefront Assets (Icons & Banners)

Storefront visual assets belong exclusively in the top-level /assets directory—not inside trunk/assets/.

Correct Naming & Resolution Rules:

  • Header Banner: banner-772x250.png
  • Retina Banner: banner-1544x500.png
  • Plugin Icon: icon-128x128.png
  • Retina Icon: icon-256x256.png
  • Screenshots: screenshot-1.png, screenshot-2.jpg, etc.

Staging Asset Changes:

Add new assets:

svn add assets/icon-128x128.png assets/icon-256x256.png --force
Enter fullscreen mode Exit fullscreen mode

Remove obsolete assets (e.g., if you replace a JPG with a PNG):

svn rm assets/icon-256x256.jpg
Enter fullscreen mode Exit fullscreen mode

Step 5: Commit Your Changes

Once your trunk changes, new tags/, and /assets additions are ready, deploy everything to WordPress.org in a single atomic commit:

svn ci trunk/ tags/1.0.8/ assets/ -m "Release version 1.0.8: Implemented new features and bug fixes."
Enter fullscreen mode Exit fullscreen mode

Tip: You will be prompted for your WordPress.org username and dedicated SVN password (not your standard account login password).

Step 6: Verify the Live Deployment

After committing, verify that your changes reached the remote WordPress.org SVN server:

Verify readme.txt Stable Tag: 

svn cat https://plugins.svn.wordpress.org/your-plugin-slug/trunk/readme.txt | grep "Stable tag"
Enter fullscreen mode Exit fullscreen mode

Expected Output:

Stable tag: 1.0.8
Enter fullscreen mode Exit fullscreen mode

Verify Remote Asset Directory: 

svn ls https://plugins.svn.wordpress.org/your-plugin-slug/assets/
Enter fullscreen mode Exit fullscreen mode

This command should list all your active assets.

Troubleshooting Common WordPress Plugin SVN Update Gotchas

Even with a solid workflow, issues can arise. Here are some common problems and their solutions when performing WordPress Plugin SVN Updates:

1. Banners or Icons Not Updating on the Live Directory Page?

If svn ls confirms your image files are uploaded, but the live WordPress.org page still shows old graphics, don't panic. WordPress.org uses a global CDN cache for storefront assets. It can take 30 minutes to 4 hours for newly committed banners and icons to invalidate and display globally. Try checking in a private/incognito window.

2. Vendor / Composer Dependency Bloat

If your plugin uses Composer, avoid adding development packages (like squizlabs/php_codesniffer or wp-coding-standards) into your SVN repository. These are for development only and add unnecessary bloat to your production plugin.

Run Composer with the --no-dev flag before staging vendor dependencies:

composer install --no-dev --optimize-autoloader
Enter fullscreen mode Exit fullscreen mode

Only stage vendor/autoload.php and production package subdirectories to keep your SVN repository clean and lightweight.

3. "Working Copy Is Locked" Error

If an SVN operation is interrupted mid-transfer, your local working copy might become locked, preventing further operations. Clear local locks with:

svn cleanup
Enter fullscreen mode Exit fullscreen mode

Quick Reference Cheat Sheet

Here's a handy table summarizing the essential SVN commands for WordPress plugin updates:

Action Command
Check Local Status svn status
Copy Trunk to New Tag svn copy trunk tags/1.0.8
Stage New Files svn add filename
Remove Tracked Files svn rm filename
Commit All Changes svn ci -m "Commit message"
Inspect Remote Files svn ls https://plugins.svn.wordpress.org/your-plugin-slug/
Clear Locked Working Copy svn cleanup

Key Takeaways

  • Understand SVN Structure: trunk for development, tags/X.X.X for immutable releases, and /assets for storefront visuals.
  • Local Preparation is Key: Always update your plugin version in the main PHP file and readme.txt before any SVN commands.
  • Atomic Commits: Bundle all related changes (trunk, tags, assets) into a single svn ci command for consistency.
  • Mind the Cache: Storefront asset updates can take time to propagate due to CDN caching.
  • Keep it Lean: Exclude development-only Composer dependencies from your production plugin bundle.

By sticking to this structured workflow, updating your WordPress plugin becomes a fast, reliable, and error-free routine. Happy coding!

Top comments (0)