After a discussion on the WordPress Answers Stack Exchange yesterday, I thought it would be a good idea to explain the different ways you can develop plugins for WordPress. Since the official plugin repository uses Subversion for version control, that’s the obvious first choice when you’re just starting your development stack. So here is, step-by-step, a tutorial on how to get started using Subversion to track changes in and eventually publish your WordPress plugin.
Things you’ll need to follow along:
- A WordPress plugin to write
- TortoiseSVN (Mac users see my note about SCPlugin)
- A WordPress.org account
First and Foremost
The very first step is to create an account on WordPress.org. You’ll use this account to control your plugin, post to the support forum, and edit the Codex. Chances are that you already have an account. But if you don’t, it would be a good idea to create one.
Get Hosted
Next, you’ll need to ask the WordPress.org team to host your snazzy new plugin. All you need at this point is a name and an idea. It can take anywhere from an hour to a few days to get your application approved, so don’t worry if you don’t have any code written yet.
Using Subversion
Using version control is the first lesson every developer should learn, unfortunately it’s often a lesson learned through painful experience when something goes wrong. Let me tell you this, being able to “undo” a bunch of changes you’ve made over several folders is an ability worth its weight in gold – assuming it weighed the same as a 600-lb gorilla.
If you haven’t used version control yet, you should start. Now. Right now. Which is convenient, because we’re going to!
If you haven’t done so already, download TortoiseSVN. It’s a Windows GUI for Subversion that allows you to do all the fancy version control you need to without ever having to touch the command line. Purists might tell you to start with the command line first, but I know how intimidating that can be … so we’ll start with the easy-to-use GUI instead.
A Note for Mac Users
Unfortunately, I don’t have a Mac, so I can’t give you screenshots or a guided walkthrough of a commit process. However, I have it on good authority that SCPlugin provides the same functionality with a very similar UI. The pictures won’t look the same, but you should be able to follow the same steps as outlined below.
Check Out the Repository
Let’s say your plugin application has been approved and you’ve finally received the “go ahead and get started” email from the WordPress team. Great! Find a place on your computer where you want to keep your plugin, and create a new folder for it – I keep most of my stuff inside a “/WP-Plugins” folder.
Right click inside the folder and select “SVN Checkout” from the dropdown menu. Put the URL for your repository in the first box and make sure you have a folder name specified in the second box. Most likely something like “/WP-Plugins/my-cool-plugin.”
Now you’ll have an empty repository ready and waiting for your plugin. If you open the folder, you’ll see three sub-folders: branches, tags, and trunk. We’re going to do all of our development in trunk.
Create a First Version
If you’ve already got your plugin ready to go, great! It’s actually easier to start using the repository for version control after you submit a first version. So let’s assume that you’ve finished your first beta release (version 0.1) and are ready to release it.
Copy your entire plugin into the trunk folder. All of your PHP files, your images, your stylesheets, your JavaScript, and your readme file. Everything. Then right-click anywhere in the folder and select “SVN Commit” from the TortoiseSVN menu.
You’ll be presented with the commit window. Enter “First commit of My Cool Plugin” for a commit message, select the checkbox next to each of the new files, and click OK.
Tortoise will think for a few seconds while it talks to the WordPress server. Then it will ask for your WordPress.org username and password (to make sure you have the right to commit to your plugin). Enter these and click OK. Then, voila! Your plugin is in the repository. Well … almost …
Tag Your Release
The WordPress.org plugin repository uses version tags to control everything. Basically, the engine looks at the readme file in /trunk, reads the “stable tag” out of the file, then loads the rest of the plugin from that tag in the /tags folder. So until you tag your release, you haven’t really published your plugin.
Right-click in the folder again and select “Branch/Tag” from the TortoiseSVN menu. This brings up the tag dialog window.
The first line in the dialog should indicate that you’re in the /trunk folder (the last word in the URL should be “trunk.” In the “To URL:” field, change “trunk” to “tags/0.1” assuming you’re releasing version 0.1 of your plugin. Enter a commit message – along the lines of “Tagging version 0.1” – in the big box at the bottom and click OK.
A window will pop up explaining that you’ll need to switch to the new branch to work on it. Ignore this message, you won’t need to switch to anything.
Now right-click in the folder one more time and select SVN Update from the TortoiseSVN menu. This will update your local /tags directory with the tag folder you’ve just created.
That’s it. You’re done. Your plugin is published. But what comes next?
Making Changes
From here on out, you can change anything you want in the /trunk directory and commit it except for the readme file. You can update the readme file, but do not change the “stable tag” reference until you’re ready to release!
Let’s say you need to add a new JavaScript file to your plugin, but it needs a lot of work. Go ahead and add it to /trunk and commit the changes (you’ll be asked for your WordPress.org credentials again to commit). Do some more work on the plugin, update some stylesheets, whatever.
Then, when you’re ready to release version 0.2, you need to do three things:
- Update the “stable tag” reference in the readme file.
- Update the version number in your plugin’s main PHP file.
- Tag the new release.
- Commit the new release.
Updating the stable tag is easy. Just change it in Notepad and save the file. Then right-click in the folder and select “Branch/Tag” as before … with one difference:
TortoiseSVN will warn you about taging your local version that’s not a HEAD revision. So to keep from making an out-of-sync branch, be sure to check the “Working copy” option in the “Create copy in the repository from:” section. Then tag as a new version just like you did with 0.1 above.
This will create a new folder in the /tags folder for your new version and copy the latest changes you’ve made over to it. But you’re not done yet!
Now, right-click and select SVN Commit to commit your changes to /trunk
Why Did We Tag First?
Remember, the WordPress repository looks at the readme file to find the right version, then looks for that version in the /tags folder. By committing our tag before committing the changes in the readme file, we guarantee that the right version of the plugin will be there before WordPress needs it. Basically, you made sure /tags/0.2 existed before submitting a readme file that told WordPress to look for it.
