Releasing New Versions of your WordPress Plugins

March 5, 2011 - Reading time: 5 minutes

If you are a WordPress plugin developer, then this post is for you. There is very little documentation on how to effectively use the WordPress Subversion repository, and the repo architecture is critically flawed in its structure making “kosher” usage seem entirely buggy. Worse yet, the support in the WordPress forums is practically non-existant. For a more thorough explanation of this process, see our book on WordPress 3 Plugin Development Essentials, which features an entire chapter on dealing with SVN and the WordPress repository.

Below is the short summary of what is presented in the video.

How to release updates to your WordPress plugin (quickie version)

1. Make the updates to your code, fix any errors, add new features.
2. Update your plugin’s main file (the one with the information header) so that it references the new version of your plugin, e.g.
   Version: 0.5
3. Update your readme.txt file to describe the changes you have made, but DO NOT change the Stable Tag. This number must point to an existing directory inside your repo’s tags directory.
4. Save your files, then commit your changes to the SVN repo, e.g. svn commit . -m "My new version is ready"
5. Tag the new version using the SVN copy command to copy the trunk new a new numbered directory in tags, e.g. svn copy https://plugins.svn.wordpress.org/your-plugin/trunk https://plugins.svn.wordpress.org/your-plugin/tags/0.5
   Remember: the tagging operation is just a copy operation.
6. By performing the tagging (i.e. copy) operation, a new directory has been created inside the tags directory. So only now can you safely update your readme.txt file’s Stable Tag, e.g.
   Stable tag: 0.5
   That number acts as a pointer to the corresponding folder inside of the tags directory (it would point to https://plugins.svn.wordpress.org/your-plugin/tags/0.5 in this example).
7. Commit your changes to the readme.txt file. This will ensure that the Stable Tag attribute points to the newly created version: svn commit . -m "Updating the stable tag"
8. You should be done now, but the WordPress SVN repository has been so problematic…. keep an eye on your plugin’s download page and verify that the changes get picked up. The changes should be picked up within 15 minutes or so… if they don’t get picked up, look at the downloaded zip file carefully… does the link say one thing but the name of the zip file says something else? It’s easy to mix things up, so if you get stuck, try reviewing the steps here.

How to release updates to your WordPress plugin (Long Version)

Ok, that was too quick? Well, we left out some important geeky points. The way WordPress’ download page works is that it looks at the readme.txt file at the HEAD of the repo, and then it follows the value listed there for Stable tag. If the Stable tag lists version 0.8, then the information from tags/0.8/readme.txt is used to generate your plugin’s information page and the files in tags/0.8 are packaged up into a zip file and that’s what downloads when the user clicks the download link.

Can you see the problem with this setup? Normally, when you tag a directory in SVN, that copy is treated as a read-only reference, but in this setup, it is frequently easier and less prone to errors for you to go into the tags directory and make your edits. This is normally a bit no-no for version control!

So the safer way to do this is to develop your plugin normally inside the wp-content/plugins directory and submit to the trunk as you normally do. Once you’re ready to publish a release, go to a new folder somewhere on your hard drive and checkout your ENTIRE project, trunk, tags, and all. Then you can do your tagging operation locally, e.g. svn copy trunk tags/0.9, and that will give you a new directory. You can update that directory’s readme.txt file and your plugin’s information header, then commit all of your code (trunk and all tags folders).

Hope that helps los dudes.

-- Everett Griffiths