144

The Ultimate Step-by-Step Guide to WordPress Plugin SVN Management

Introduction

Publishing a WordPress plugin involves more than just coding. WordPress.org uses Subversion (SVN) for plugin version control, which allows you to manage plugin updates, maintain stable versions, and provide a seamless experience for users. However, many plugin authors encounter issues with SVN commands, TortoiseSVN, commit messages, and Stable Tag warnings. This guide consolidates everything you need to know to manage your WordPress plugin SVN repository effectively, based on practical experience and common challenges.

Step 1: Install TortoiseSVN and Setup Command-Line Tools

The first step in working with WordPress SVN is to have a reliable SVN client. TortoiseSVN is one of the most popular options for Windows.

Installing TortoiseSVN

Download TortoiseSVN from https://tortoisesvn.net/downloads.html.
During installation, make sure to select the option “Command Line Client Tools”. This ensures that the svn command is available in your Command Prompt.
Restart your computer after installation.

Verify Installation

Open Command Prompt and run:

svn --version

You should see output similar to:

svn, version 1.14.3 (rXXXX) compiled Apr 15 2024, 16:22:31

If you see ‘svn’ is not recognized’, it means the command-line tools were not installed. Re-run the installer and ensure the command-line client is selected.

Step 2: Checkout Your Plugin Repository

Once TortoiseSVN is installed, you need to download your plugin repository to a local folder.

Create a Local Folder

Create a folder on your computer for your plugin SVN checkout, e.g.: C:\wp-svn\smartupworld-feed-author-control.

Perform SVN Checkout Using TortoiseSVN

- Right-click the folder → SVN Checkout…
- In the dialog:

URL of repository	https://plugins.svn.wordpress.org/smartupworld-feed-author-control
Checkout directory	The folder you created, e.g., C:\wp-svn\smartupworld-feed-author-control
Revision	HEAD (latest version)
Depth	Fully recursive

Click OK. TortoiseSVN will download the repository structure:
- /trunk/ – main development folder
- /tags/ – snapshot folders for stable releases
- /branches/ – optional for development branches
- /assets/ – optional for plugin page images

Step 3: Add Plugin Files to Trunk

Copy your plugin files into the /trunk/ folder. Typical files include:

Main plugin PHP file: smartupworld-feed-author-control.php
Readme files: readme.txt and optionally README.md
Other necessary PHP, JS, or CSS files

Commit Files Using TortoiseSVN

Right-click the /trunk/ folder → SVN Commit…
Check all new files to add.
Important: In the Message / Log Message field, write a descriptive commit message, e.g.: Initial commit of Smartupworld Feed Author Control plugin
Click OK. Your files will be uploaded to WordPress SVN.

Important: WordPress.org has a pre-commit hook that will reject empty messages. Always provide a meaningful message.

Step 4: Create a Tag for a Stable Release

Tags are snapshots of your trunk for stable plugin releases. Never use /trunk/ as the stable version.

Create a Tag in TortoiseSVN

- Right-click the /trunk/ folder → TortoiseSVN → Branch/Tag…
- In the dialog:

To Path	/smartupworld-feed-author-control/tags/1.0.0
Create copy in repository from	Working copy ✅
Log Message	Tagging version 1.0.0

Click OK. TortoiseSVN will copy the trunk files into /tags/1.0.0/.

Verify the Tag

Open your browser: https://plugins.svn.wordpress.org/smartupworld-feed-author-control/tags/
You should see: 1.0.0/
The tag is now a stable snapshot; do not make changes directly in the tag.

Step 5: Understanding Working Copy vs Tag

When creating a tag, TortoiseSVN asks which revision to copy:

Working copy: Copies your local files (recommended)
HEAD revision: Copies the latest committed files from SVN
Specific revision: Copies a particular SVN revision

The resulting tag is **not a working copy** — it is a read-only snapshot. You continue development in /trunk/, and create new tags for future versions.

Step 6: Handling Stable Tag Warnings

WordPress reads the Stable Tag in your readme.txt to determine which tag is the official stable release. Common warnings include:

The Stable Tag field is invalid: The folder specified in SVN does not exist.
The Stable Tag field is missing or invalid: WordPress does not allow using /trunk/ as stable.

Fixing the Stable Tag

Check your existing tags in SVN: https://plugins.svn.wordpress.org/smartupworld-feed-author-control/tags/
Ensure the folder you want to use exists, e.g., 1.2/.
Update your /trunk/readme.txt to include exactly:
```
Stable Tag: 1.2
```
Commit the updated readme.txt to /trunk/ with a descriptive message, e.g.: Updated Stable Tag to 1.2
WordPress will read this commit and associate the stable tag with /tags/1.2/.

Step 7 Continued: Uploading Plugin Page Assets

Once the images are added, right-click the /assets/ folder and select SVN Commit…
Enter a descriptive commit message, e.g.: Added plugin page banner and icon
Click OK to upload the assets to the repository

After a few minutes, these assets will appear on your WordPress.org plugin page, enhancing the visual appeal and professionalism of your plugin.

Step 8: Future Plugin Updates and Tagging New Versions

Once your plugin is live, you will frequently update the plugin for bug fixes, new features, or security patches. Here’s the recommended workflow:

1. Update /trunk/ Locally

Edit files in your local /trunk/ folder.
Test thoroughly to ensure there are no issues.
Commit changes to /trunk/ using TortoiseSVN with a descriptive message, e.g., Fixed issue with feed author control function

2. Create a New Tag for the Release

Right-click the updated /trunk/ → TortoiseSVN → Branch/Tag…
To Path: /smartupworld-feed-author-control/tags/1.3 (replace with the new version)
Copy from: Working copy
Log Message: Tagging version 1.3
Click OK

3. Update readme.txt

Change the Stable Tag in /trunk/readme.txt to match the new tag folder, e.g.: Stable Tag: 1.3
Commit this updated readme.txt to /trunk/

4. Verify

Check the tag folder in the browser: https://plugins.svn.wordpress.org/smartupworld-feed-author-control/tags/1.3/
Ensure WordPress recognizes the stable tag on the plugin page.

Step 9: Common Errors and How to Solve Them

Error 1: Commit blocked by pre-commit hook

Message: Please provide commit message that describes the changes you are making

Solution: Always enter a meaningful commit message in TortoiseSVN’s Log Message field. For example: Initial commit of plugin files or Tagging version 1.2

Error 2: Stable Tag field is invalid

Message: The Stable Tag field is invalid, the specified SVN tag /tags/1.2/ does not exist

Solution:

Check that the tag folder exists in SVN exactly as named in readme.txt
Update readme.txt Stable Tag line to match the folder exactly
Commit the updated readme.txt to /trunk/

Error 3: /trunk/ used as stable

Solution: Never use /trunk/ as the Stable Tag. Always create a snapshot in /tags/ for each release. This allows WordPress to roll back to previous versions if needed.

Step 10: Quick Reference Table for SVN Workflow

Action	Local Folder	SVN Path	Notes
Initial commit	/trunk/	/trunk/	Add all plugin files, provide descriptive commit message
Create a tag	/trunk/	/tags/1.x/	Snapshot of trunk at release version, do not edit tag
Update Stable Tag	/trunk/readme.txt	/trunk/	Set Stable Tag to match the tag folder
Commit plugin page assets	/assets/	/assets/	Add banners, icons, and other images for plugin page
Future plugin updates	/trunk/	/trunk/	Edit, test, commit, then create new tag for release

Step 11: Summary and Best Practices

Always use descriptive commit messages; WordPress pre-commit hooks will block empty messages.
Never use /trunk/ as the Stable Tag — always create a tag folder under /tags/.
Ensure readme.txt Stable Tag exactly matches the tag folder name (case-sensitive).
Commit changes to /trunk/ first, then create tags for stable releases.
Keep /trunk/ for active development, /tags/ for release snapshots.
Upload plugin page assets to /assets/ for a professional appearance.
Check your SVN repository using the browser or TortoiseSVN Repo-browser to verify tags and files.
Wait a few minutes after commits for WordPress.org to update plugin data.

Conclusion

Managing WordPress plugins with SVN may seem complex at first, but following a systematic workflow ensures smooth releases and avoids common errors like invalid Stable Tags or blocked commits. By keeping a clean /trunk/ for development, creating tags for stable releases, providing descriptive commit messages, and properly updating readme.txt, plugin authors can maintain a professional and reliable workflow. Using TortoiseSVN and following this guide, you can confidently commit, tag, and manage your plugin versions while keeping WordPress.org happy.