Are you comfortable building plugins for WordPress? Have you made some for personal (or paying) projects that would be useful to others? Did you know that WordPress 2.7 offers direct download of plugins from the Plugin Repository? Think of how much traffic that could build compared to all those blog comments you’ve written. I’m starting to hear your thoughts of “I need to get me some of that plugin repository action!”. You’ve come to the right place to learn.
A repository is just a fancy way for saying a place to store your data much like an FTP server. What makes using one so important is that you create versions of files so that you can always roll back if you make mistakes. The WordPress.org site contains some very good information on How To Use Subversion to create / contribute to a plugin…if you are a fan of command line tools. Some people probably prefer that approach – just like using vi as a text editor. However, I find graphical based user interfaces easier and more efficient to use.
This tutorial is for those who – like me – use Dreamweaver for web development and want to maintain their plugin code on the WordPress repository through it. For those who use Eclipse, you can follow a similar process using SubClipse. The two key pieces of the puzzle are:
- TortoiseSVN – An SVN client for Windows that makes version management simple.
- SubWeaver – A Dreamweaver extension to integrate SVN commands through Tortoise.
Setup your WordPress.org account and plugin repository
The first thing you will want to do is go to WordPress.org > Extend > Plugins and register for an account. The contact information (name, email, website, etc) you provide will show up with any plugins that you create or contribute to.
Since you’re on the site and ready to start your first plugin, go to the Add a Plugin form and provide the appropriate details (name, description, url). Note that it may take 24 – 48 hours for your plugin request to be approved, but this will create a new repository for your plugin.
Install Tortoise and SubWeaver
Download and install Tortoise SVN from http://tortoisesvn.tigris.org. You will have to restart your computer for the changes to take effect. After that has completed, you will want to download and install Subweaver from http://code.google.com/p/subweaver/
When you are looking at the file explorer in Dreamweaver, you will now see a new SubWeaver sub-menu that I will explain the primary uses of it as we go along.
Create a local repository
You will need a folder on your hard drive to store the plugin files / folders. Find the folder in Windows Explorer and right-click on it to select SVN Checkout. You will have to add the repository information which was specified when you completed the Add a Plugin form. The repository path should start with http://svn.wp-plugins.org/ as the image at right shows for Idealien Category Enhancements.
You could do this through Dreamweaver directly, however I prefer to do the initial checkout by Tortoise so that when I create the site in Dreamweaver it already contains the standard SVN structure.
Understanding the structure of a repository
There are 3 different locations where you can place code which are loosely based on the analogy of a tree:
- Trunk represents the area where your active development goes. When starting your plugin, it will be where you add your first files. It is the latest and greatest so might not be ready for public consumption.
- Tags are for specific versions of your plugin. Any time you commit significant changes to your trunk (i.e. a new version) you should create a new tag and update the readme.txt file to indicate what the newest release is. I have gotten into the habit of developing on a separate WP installation (easier for testing, debug, etc) and as a result the code in the trunk usually mirrors the most up to date tag available.
- Branches are for working on enhancements or code you would like others to beta test or build in isolation of other functionality. When you’re satisfied with a particular branch, you will have to merge the changes into the trunk. Smaller scope plugins usually won’t use branches.
Or as the wordpress.org site puts it:
Each time you make a formal release of your plugin, you should tag a copy of that release’s code. This lets your users easily grab the latest (or an older) version, it lets you keep track of changes more easily, and lets the WordPress.org Plugin Directory know what version of your plugin it should tell people to download.
Add, Modify, Delete or just Commit!
You now have a link between the repository and your local computer. Work with the files on your local PC until you are satisfied and ready to commit them to the repository.
- Highlight all of the files that you have modified.
- Right click and chose to SubWeaver > Commit
- Dreamweaver will show you the SVN log in which it compares every file on your PC against the repositor and the action (add, modify, delete) it did to the version in the repository as well.
- If you want to ensure you don’t miss anything, select the top-level folder for your plugin and then commit. Note that if you do this and you have added / deleted any files, you will have to specifically check their checkbox under the changes made window.
The update process on the repository server will take a few minutes to show up in the Plugin Directory.
Updates and Merges
The work scenario I described above is written on the assumption that you are the only one editing files for your plugin. If you are collaborating on another plugin, before you start to work on changes you will want to execute an SVN update to ensure you have pulled the latest files from the server to your local PC.
It is possible (read: likely) that at some point in time you will encounter a scenario where someone else has updated the files which you are working on in between when you updated your files and when you went to commit. You now must merge your changes with theirs which is the bane of many developers. While Tortoise / SubWeaver do have tools built in to compare files, I have found that WinMerge is a better tool built specifically for this task. You can install it and configure it with Tortoise under the Settings > External Programs menu.
Great article. Thanks for the sharing.
You do not have to tag every commit to trunk. In fact, you shouldn’t, it’s redundant.
Tag when you release.
Big difference.
There is something funny in how wordpress.org is scripting the releases with respect to tags. I’m going to have to dig out the script to see exactly what they are doing.
But in general, develop in trunk and increment your version independently. When you’re ready to release, then update your readme.txt and make a tagged copy. Or use a branch, then merge into trunk, update version, copy to tags for release.
Thanks for the comment Dave. I’ve updated the trunk, tag, branch descriptions so that it is a little clearer.
Great tutorial, it goes directly to the objective of sharing in wordpress. But I am a little unsure about what is SVN and if I could implement a technique like this with my other pieces of code. Can Dreamweaver also work with a remote repository in you server, for example ?
Thanks a lot !
Thanks Rodolfo. Short answer is that in order to have your plugins show up in wordpress.org extend / plugins gallery, you must use their SVN repository. But for other pieces of code…If you are very organized with your digital materials and working in isolation on a project, a system like SVN “isn’t” specifically required. You could use Dreamweaver to FTP your files to the server, make copies of the entire code base before you make any changes and “effectively” manually track versions if you want.
However, a version management system like SVN makes that process a lot easier once you get familiar with it. It also takes up a lot less time / disk space once you do start to use it – not to mention the benefits which come when you are working on a project collaborating with other developers. I’m sure others would have different opinions on the matter, but once I get beyond the alpha concept stage for any code, I usually setup a repository of some form so that the code base is not entirely dependant on me (and one hard drive).
Thank’s for this nice tips
just want contribute but it so hard 🙁
how we know if our plugin was publish? because i have input my plugin 3 month ago but until now my plugin not published? there is notification or something else?