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.
- 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.
Hey Eric,
Thanks for the highly helpful tutorial. I just followed this to publish my first WP plugin and it was an absolute lifesaver!
Cheers,
- Kezz
I’m glad I was able to help, and I look forward to seeing more contributions from you in the repository!
Can you design a wp plugin? Novices here we need someone to design one for us
Short answer: yes. Contact me here with more information and I’ll get back to you.
Eric,
great stuff, could you point me to something on using DIFF to create fixes for plugins etc.
Chers,
Andy
Hey Eric,
Brilliant post. It helped me alot. I followed exactly the same steps as mentioned by you to update a new version of my plugin. But for some reason, no notification is send to existing plugin users nor the new version gets updated on the wordpress download plugin screen. But when you download the plugin, the latest tagged version is downloaded.
I am really confused now. dont know what is going wrong. Can you please help me?
this is my plugin http://wordpress.org/extend/plugins/kc-related-posts-by-category/
Notifications aren’t supposed to go out. WordPress will automatically check with the repository twice per day to see if a new version is available. If there is (if the version in the repo is > the version on the site), it will alert the administrator and ask them to update.
I didn’t see a problem with your plugin as far as its location in the repository or its tag structure, but WP isn’t recognizing anything beyond version 1.0. I suggest emailing plugins [at] wordpress [dot] org and asking them to take a look …
Hey Eric,
Really appreciate for taking out time and having a look at the plugin. I have emailed them and waiting for the response.
But I guess I followed your document for updating the plugin. While uploading it for first time, I have followed some other document and it went wrong.
Now for second plugin, I followed your document and everything seems to be perfect. Wish I had done the same before.
Thanks alot for your help. Really appreciate..
Hey Eric,
I found out what mistake I was doing. The actual version shown on the download page is picked from main .php file of the plugin. So in the top we usually specify the version field.
I was not updating that value and hence it was still showing the old version.
Thanks again for all your help.
Hey kunal, I found this post very helpful, even i followed the same steps to update my plugin to newer version, but fortunately even i made same mistake as you did. I forgot to update the version in the main .php plugin file and now it is not showing the new version on the download button of the plugin page on wordpress. But when you download the plugin it is of newer version. Plugin URL – http://wordpress.org/extend/plugins/shortcode-collection/
Any Help is much appreciated!!
Waiting for your reply.
Thank you so much for this useful WordPress SVN guide. This is the only place what I could find the complete details guide so far.
Thank you again.
I am having the weirdest issues and found your blog. i went through and now know we where doing things correctly…BUT..lol no luck.
Followed your instructions and i KEEP getting the same error onb checkout *(below)..BUT he did exactly the same (on Linux) and it worked, fyi i am on Windows 7
this is the error that KEEPS coming up after trying to checkout.
Checkout from http://plugins.svn.wordpress.org/wp-online-store, revision HEAD, Fully recursive, Externals included
‘http://plugins.svn.wordpress.org/wp-online-store’ isn’t in the same repository
as ‘http://plugins.svn.wordpress.org/’
any thoughts would be a lifesaver.
Garfield
Unfortunately no, I have no idea what’s going on. And to clarify, I actually wrote this tutorial using the same steps I follow on my Windows 7 box when I update plugins. And I’ve verified a few weeks ago that things are still working (for me at least) when I helped another developer update their system.
The only thing I can think of is that maybe your Tortoise installation is broken. Maybe try to re-install Tortoise and try again? But I’ve never seen that error message before …
Thanks for the tutorial. I’ve just published my first plugin: Simple Social Buttons. Your “how to” was very helpful for me.
I find your post one of the most clear I found, and yet, there are so many steps!
I still have questions, though, because so many people saying “just do the changes locally and then “add” and “commit”… gave me so many bad experiences trying to un-do every trial and error… Adding a new folder (tag) that I got by duplicating the previous tag only gives me MORE NIGHTMARES! (Error: “This or that already versioned”
The screenshot Tag1.png shows in both “from” and “To” the same local trunk. And then you say “click in it again”, and I don’t know what you are refering to.
Could you explain?
Also, when I copy the whole folder or files from the trunk to a new tag (folder?) in the respository, there’s no command that works for copy/update/checkout the copied files to the local computer.
I use RapidSVN, but I tried before with another applications and same issues.
Once you are used to windows and folders, GUIs like these are not intuitive enough to make you feel like adopting it.
Regarding the screenshot. That’s the dialog box that appears when you first right-click and then select “Branch/Tag.” You have to click the “To URL” field and edit it to change /trunk to /tags/0.1 (assuming you’re tagging version 0.1).
If you’re tagging, try to avoid copying the entire /trunk directory anywhere. It has hidden /.svn folders inside it that Subversion uses to track individual file revisions. That’s why you’re having issued with the “This or that already versioned” message.
If at all possible, use Subversion to create the tag rather than trying to move any directories or files yourself. It’s more efficient to use the GUI tools than to do it manually. I recommend TortoiseSVN because it integrates well with Windows and the regular directory structure and doesn’t require you to learn command line functions.
This post has helped me alot. It has helped to add my First plugin in the wordpress plugin repository.
Thanks a lot man. You can check it out here about my plugin – http://www.wordpress.org/extend/plugins/shortcode-collection/ Thanks once again man.
Also the plugin was causing some fatal error. i just now corrected it.
now the corrected and working plugin can also be downloaded from – http://agnelwaghela.bammz.net/shortcode-collection/
Fantastic Tutorial, thanks so much for the write up! I am very happy that you also included the Making Changes section at the bottom.
Very useful tutorial.
I am having a weird issue and found your blog.
I’m a little confused about submitting a plugin. I have two small plugins that I used for a few months, and I decided to give them to others. I tried a couple of times to send them but the only thing that I get is a email containing “This plugin will not be included.”.
The plugins are: http://www.greatwpplugins.com/easy-post-subtitle/ and http://www.greatwpplugins.com/extra-category-content/.
The plugin name is unique.
I have no idea why they rejected my plugins.
Any thoughts would be a lifesaver.
Thanks for this. Just what I needed as I set about the task of publishing my first plugin today!
simple-youtube-shortcode
Very very helpful tut.
All was going well…
I have a problem… if you can shed some light, would be much appreciated.
I get to the stage… Tag Your Release
The part ‘From WC to URL’ it shows in your screenshot a file referenced on the C drive.
When I get to this stage I only have http://plugins.svn.wordpress.org/….. and cannot select hard drive.
I tried keeping it as the http but when pushing, it does create a folder version 1.0 but inside this folder, instead of the files it contains a duplicate – branches, tags, trunk.
Anything obvious that might be going wrong?
Many thanks
A short followup…
The following line “Right-click in the folder again”… i found i had to ensure i right clicked inside the trunk folder. The previous right click mentioned was in the master folder.
I still had the reference to http and not C:// but it has seemed to work ok.
I guess this is solved.
Thanks again for the help!
Actually, you did that just fine. The reference should be to the http location of the directory. In my example, I was committing instead to a local repository rather than a remote one. So you’re doing everything the right way
Thanks for the reply. Yes, all working fine!
Just wanted to say thank you for the fantastic guide! Had my first WordPress plugin approved and was kind of stuck how to set up svn on my home Windows PC and get it working properly, but your steps made it a breeze.
Thank you, Kunal.
It is helpful for me.