Releasing New Versions of your WordPress Plugins

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 http://plugins.svn.wordpress.org/your-plugin/trunk http://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 http://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.

4 thoughts on “Releasing New Versions of your WordPress Plugins

  1. Thanks for the video. You are right, their documentation is terrible. I will try out what you suggested and let you know the outcome!

  2. dude, thanks, I was going bonkers .. and I’ve had years of experience in svn.. but my current f/t job uses git, so I guess I was resisting this…
    anyway, damn, the instructions at: http://wordpress.org/extend/plugins/about/svn/ absolutely steered me in the most confusing directions .. it asks you to work in your local copy and then manually create the new directory under tags and then manually copy your files in there, and then do the svn cp and things just didn’t work ..

    After reading your documentation, I realized I could simply do a “svn copy trunk tags/tagnum”, (after checking out my repos into a local working copy of course)… talk about easy frackin button!
    Thanks

  3. I should point out the super-fast version for those of you who are daring enough to try it:

    1. Make your edits, update your readme.txt to reflect the new version, and update the “stable tag” to this new version (yes, update it BEFORE that directory exists).
    2. Commit your changes (the head is ON now…)
    3. Quickly copy over the trunk to the tags folder as outlined above, e.g.
    svn copy http://plugins.svn.wordpress.org/your-plugin/trunk http://plugins.svn.wordpress.org/your-plugin/tags/0.5

    That works, but it’s a potentially problematic: if WordPress scans its directory before you’ve copied over the trunk, it will package up the code at the head in the TRUNK. At that moment, that code should be identical to what you’re copying into the new tags directory, but you have to ask “when will WP re-scan the repo?” because you definitely don’t want the code at the HEAD to be in your zip file after you’ve made other changes.

Comments are closed.