Updating the WordPress plugin repository with SVN on Mac
Having recently switched my development platform from Windows to Mac, and being a published WordPress plugin author, I needed to find a Mac-based replacement for the excellent Windows-based TortoiseSVN in order to update my plugins on the WordPress plugin repository.
There are many ways to get set up with SVN on a Mac, some free, some not. The method described in this article is by no means the only way to do it, but it worked well for me, and it’s completely free.
Note: I use OSX 10.8.2 Mountain Lion on a MacBook Pro. I have assumed that you already have a plugin approved and published on the WordPress plugins repository.
This is a long article with plenty of illustrations, and it’s worth reading through it at least once before you start to follow the steps described in it.
1. Install SVN
SVN no longer comes bundled with OSX, so you have to install it. There are two ways to do this. If you have the Mac development toolkit Xcode installed, use method 1a. If not, you can either install Xcode anyway (free from the App Store) and use method 1a, or you can use method 1b.
1a. Launch Xcode and open Preferences. You’ll see a window like the screenshot below. Select and install the Command Line Tools (this bundle includes SVN). Obviously my screenshot shows them as already installed.
1b. Go to http://developer.apple.com/xcode and click the link marked “Looking for additional developer tools? View Downloads”. You will need to sign in with your Apple ID and possibly go through registration for a developer account if you haven’t already done this. Eventually you will get to a downloads list screen as shown below, and you should select and install the Command Line Tools bundle for Mountain Lion as shown.
You may deduce from this that simply installing Xcode is by far the easiest method, and in fact that’s exactly what I did.
2. Install and configure svnX
svnX is the SVN graphical interface I chose to avoid having to use the command line to handle checkouts, commits, etc. It’s compact, free, and although it doesn’t integrate into Finder like TortoiseSVN integrates into Windows Explorer, it’s still pretty easy to get used to, and I’ve actually come to prefer its approach. When you have installed it, launch it and open its preferences. You’ll see a window like the one below, and all you have to do is verify that it has found SVN and is showing the correct path. You may also like to change the choice of Diff application (for file compares) – I use and love TextWrangler, so I selected that.
3. Connect to your plugin’s repository
For each plugin that WordPress.org approves for the repository, it sends you an email containing the SVN URL, something like this: http://plugins.svn.wordpress.org/plugin_name/ – you’ll need that URL in this step, and you’ll need your WordPress.org login details.
In svnX, open the Repositories window, and click the ‘+’ button to add a new repository. In the first field, enter the plugin name, and then populate the remaining fields with the information I mentioned above. After entering the last field, tab away from it and the entry is saved. Here’s what the Repositories window looks like:
4. Checkout your repository to a local folder
Now you have to set up a local working copy of the plugin using the repository, so you have files that you can work on and, later, re-commit back to the repository.
I’d strongly suggest that you have a test installation of WordPress installed on your Mac and running on MAMP or XAMPP. This test installation can be used for plugin development, so you can immediately see the effects of changes you make to the local working copy of your plugin. If you don’t have this set up, go and do it now.
In the Repositories window of svnX, double-click your plugin’s entry in the list. A new window will open, something like the screenshot shown below.
This window shows all the commits you have made in the upper half, and the file structure of each commit in the lower half. It will take a few seconds to populate as shown, and the most recent commit will be selected, which is fine.
In the lower half, single-click the “trunk” folder and wait to see its contents shown. Then click the “Checkout” icon at the top of the window. In the location selector that drops down, select the plugins folder of your WordPress test installation and click the “Checkout” button. A working copy of your plugin will be created in your plugins folder.
5. Edit and test your plugin
Now you can activate the plugin, test it, edit it, improve it, etc. For now you’re done with svnX so feel free to hide it. Work on the plugin just as you would any local development project, by using Finder to select source files, your favourite text editor to edit them and a selection of browsers for testing.
Don’t forget to update the version number information in the plugin’s main PHP file and readme file before you consider the plugin ready for release.
6. Commit the new version to Trunk
When updating a WordPress plugin, the new version always gets saved in the “trunk” folder, overwriting previous versions, and then a “tag” is created in a folder of its own, and this tag folder is used by WordPress to create the downloadable zip file in the repository.
First of all we need to commit to trunk. Open svnX’s Working Copies window and you’ll see your plugin name and local location, like the screenshot below.
Double-click your plugin and a detail window will open showing the changes you have made, something like this:
Modified files show an ‘M’ on the left. Added files show ‘?’ and you will need to select them and click ‘Add’ before you can commit. Deleted files show ‘!’ and you will need to select them and click ‘Remove’ before you can commit. Then, to commit, select all the files and click ‘Commit’. You will be asked to enter a commit message as you commit the new version. I keep my commit messages pretty brief since all update information is in the changelog section of my plugins’ readme files anyway.
7. Create a versioned Tag
Now you’ve committed to trunk, you need to create a tag of the new version, which is pretty easy.
Go back to svnX’s Repositories window and double-click your plugin, so that you see the two part window as before. Single-click the “trunk” folder as before and wait for the folder contents to be shown.
Now click the “Copy” icon at the top of the window. In the drop down window that appears, select the “tags” folder as shown below.
In the name field, delete the word “trunk” and enter the version number of your release, then enter a brief commit message and click “Commit”. That’s it – you’re done and you can close svnX if you want.
8. Check all is OK
As you may know it takes WordPress between 10 and 20 minutes to update the repository with the new version of your plugin, so go and make a coffee, answer some emails, have a smoke, whatever, and then go to your plugin’s page in the repository (e.g. http://wordpress.org/extend/plugins/zigweather/) to make sure all is OK.
Simply repeat steps 3 to 8 if you have more than one plugin as I do, and repeat steps 5 to 8 each time you want to release a new version.
Helpful? Confusing? Found a mistake? Leave a comment below!
NOTE: apparently there is, or at least was, an SVN client for OSX called “Zigversion”. I should point out that Zigversion is not related to ZigPress in any way.